![(please configure the [header_logo] section in trac.ini)](/repos/chrome/site/pj.jpg)
- Timestamp:
- Jul 7, 2011 7:46:33 AM (13 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/branches/projects/2.0-dev/pjsip/include/pjsua-lib/pjsua.h
r3500 r3609 325 325 #endif 326 326 327 /** 328 * Is video enabled. 329 */ 330 #ifndef PJSUA_HAS_VIDEO 331 # define PJSUA_HAS_VIDEO PJMEDIA_HAS_VIDEO 332 #endif 327 333 328 334 /** … … 2439 2445 * Maximum number of simultaneous active video streams to be allowed 2440 2446 * for calls on this account. Setting this to zero will disable video 2441 * in calls on this account .2442 * 2443 * Default: 02447 * in calls on this account, regardless of other video settings. 2448 * 2449 * Default: 1 2444 2450 */ 2445 2451 unsigned max_video_cnt; 2452 2453 /** 2454 * Specify whether incoming video should be shown to screen by default. 2455 * This applies to incoming call (INVITE), incoming re-INVITE, and 2456 * incoming UPDATE requests. 2457 * 2458 * Regardless of this setting, application can detect incoming video 2459 * by implementing \a on_call_media_state() callback and enumerating 2460 * the media stream(s) with #pjsua_call_get_info(). Once incoming 2461 * video is recognised, application may retrieve the window associated 2462 * with the incoming video and show or hide it with 2463 * #pjsua_vid_win_set_show(). 2464 * 2465 * Default: PJ_FALSE 2466 */ 2467 pj_bool_t vid_in_auto_show; 2468 2469 /** 2470 * Specify whether outgoing video should be activated by default when 2471 * making outgoing calls and/or when incoming video is detected. This 2472 * applies to incoming and outgoing calls, incoming re-INVITE, and 2473 * incoming UPDATE. If the setting is non-zero, outgoing video 2474 * transmission will be started as soon as response to these requests 2475 * is sent (or received). 2476 * 2477 * Regardless of the value of this setting, application can start and 2478 * stop outgoing video transmission with #pjsua_call_set_vid_out(). 2479 * 2480 * Default: PJ_FALSE 2481 */ 2482 pj_bool_t vid_out_auto_transmit; 2483 2484 /** 2485 * Specify the default capture device to be used by this account. If 2486 * \a vid_out_auto_transmit is enabled, this device will be used for 2487 * capturing video. 2488 * 2489 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV 2490 */ 2491 pjmedia_vid_dev_index vid_cap_dev; 2492 2493 /** 2494 * Specify the default rendering device to be used by this account. 2495 * 2496 * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV 2497 */ 2498 pjmedia_vid_dev_index vid_rend_dev; 2446 2499 2447 2500 /** … … 2976 3029 #endif 2977 3030 3031 /** 3032 * Maximum active video windows 3033 */ 3034 #ifndef PJSUA_MAX_VID_WINS 3035 # define PJSUA_MAX_VID_WINS 16 3036 #endif 3037 3038 /** 3039 * Video window ID. 3040 */ 3041 typedef int pjsua_vid_win_id; 2978 3042 2979 3043 … … 3084 3148 /** Audio stream */ 3085 3149 struct { 3086 pjsua_conf_port_id conf_slot; /**< The conference port3087 number for the call. */3088 } aud io;3150 /** The conference port number for the call. */ 3151 pjsua_conf_port_id conf_slot; 3152 } aud; 3089 3153 3090 3154 /** Video stream */ 3091 3155 struct { 3092 pjmedia_vid_port *capturer; /**< Video capturer. */ 3093 pjmedia_vid_port *renderer; /**< Video renderer. */ 3094 } video; 3156 /** 3157 * The window id for incoming video, if any, or 3158 * PJSUA_INVALID_ID. 3159 */ 3160 pjsua_vid_win_id win_in; 3161 3162 /** The video capture device for outgoing transmission, 3163 * if any, or PJMEDIA_VID_INVALID_DEV 3164 */ 3165 pjmedia_vid_dev_index cap_dev; 3166 3167 } vid; 3095 3168 } stream; 3096 3169 … … 3118 3191 3119 3192 3193 /** 3194 * Media stream info. 3195 */ 3196 typedef struct pjsua_stream_info 3197 { 3198 /** Media type of this stream. */ 3199 pjmedia_type type; 3200 3201 /** Stream info (union). */ 3202 union { 3203 /** Audio stream info */ 3204 pjmedia_stream_info aud; 3205 3206 /** Video stream info */ 3207 pjmedia_vid_stream_info vid; 3208 } info; 3209 3210 } pjsua_stream_info; 3211 3212 3213 /** 3214 * Media stream statistic. 3215 */ 3216 typedef struct pjsua_stream_stat 3217 { 3218 /** RTCP statistic. */ 3219 pjmedia_rtcp_stat rtcp; 3220 3221 /** Jitter buffer statistic. */ 3222 pjmedia_jb_state jbuf; 3223 3224 } pjsua_stream_stat; 3225 3120 3226 3121 3227 /** … … 3191 3297 3192 3298 3193 #if DISABLED_FOR_TICKET_1185 3194 /** 3195 * Retrieve the media session associated with this call. Note that the media 3196 * session may not be available depending on the current call's media status 3197 * (the pjsua_call_media_status information in pjsua_call_info). Application 3198 * may use the media session to retrieve more detailed information about the 3199 * call's media. 3299 /** 3300 * Get the conference port identification associated with the call. 3200 3301 * 3201 3302 * @param call_id Call identification. 3202 3303 * 3203 * @return Call media session. 3204 */ 3205 PJ_DECL(pjmedia_session*) pjsua_call_get_media_session(pjsua_call_id call_id); 3206 3207 /** 3208 * Retrieve the media transport instance that is used for this call. 3209 * Application may use the media transport to query more detailed information 3210 * about the media transport. 3211 * 3212 * @param cid Call identification (the call_id). 3213 * 3214 * @return Call media transport. 3215 */ 3216 PJ_DECL(pjmedia_transport*) pjsua_call_get_media_transport(pjsua_call_id cid); 3217 #endif /* DISABLED_FOR_TICKET_1185 */ 3218 3219 /** 3220 * Get the conference port identification associated with the call. 3221 * 3222 * @param call_id Call identification. 3223 * 3224 * @return Conference port ID, or PJSUA_INVALID_ID when the 3304 * @return Conference port ID, or PJSUA_INVALID_ID when the 3225 3305 * media has not been established or is not active. 3226 3306 */ … … 3571 3651 unsigned maxlen, 3572 3652 const char *indent); 3653 3654 /** 3655 * Get the media stream index of the default video stream in the call. 3656 * Typically this will just retrieve the stream index of the first 3657 * activated video stream in the call. 3658 * 3659 * @param call_id Call identification. 3660 * 3661 * @return The media stream index or -1 if no video stream 3662 * is present in the call. 3663 */ 3664 PJ_DECL(int) pjsua_call_get_vid_stream_idx(pjsua_call_id call_id); 3665 3666 /** 3667 * Start, stop, and/or manipulate video transmission for the specified 3668 * call. This would trigger a re-INVITE or UPDATE to be sent for the 3669 * call. This function may add, remove, or modify existing video media 3670 * stream, depending on the media index specified (the \a med_idx argument). 3671 * 3672 * To add a new or edit existing video stream (for transmission), specify 3673 * a valid video capture device ID or PJMEDIA_VID_DEFAULT_CAPTURE_DEV in 3674 * the \a cap_dev argument. If \a med_idx is set to default stream (-1), 3675 * then the function will modify existing video stream if one exists, or 3676 * add a new one if it doesn't. If \a med_idx is set to a specific stream 3677 * index, the function will modify that video stream. Otherwise if \a med_idx 3678 * is set to value larger than the current media count, a new video stream 3679 * will be added to the call. 3680 * 3681 * To remove an existing video stream, specify PJMEDIA_VID_INVALID_DEV in 3682 * \a cap_dev argument. If \a med_idx is set to default stream (-1), this 3683 * will remove the default/first video stream in the call, otherwise 3684 * application can put a specific value to request removal of that particular 3685 * video stream. 3686 * 3687 * @param call_id Call identification. 3688 * @param med_idx The media stream index. Currently the value MUST 3689 * be -1 to denote the default video stream in the 3690 * call. 3691 * @param cap_dev To add or modify existing video media stream, 3692 * specify PJMEDIA_VID_DEFAULT_CAPTURE_DEV to use 3693 * the default capture device as configured in the 3694 * account, or specify a specific capture device ID. 3695 * To disable an existing video stream, specify 3696 * PJMEDIA_VID_INVALID_DEV for this parameter. 3697 * 3698 * @return PJ_SUCCESS on success or the appropriate error. 3699 */ 3700 PJ_DECL(pj_status_t) pjsua_call_set_vid_out(pjsua_call_id call_id, 3701 int med_idx, 3702 pjmedia_vid_dev_index cap_dev); 3703 3704 /** 3705 * Get media stream info for the specified media index. 3706 * 3707 * @param call_id The call identification. 3708 * @param med_idx Media stream index. 3709 * @param psi To be filled with the stream info. 3710 * 3711 * @return PJ_SUCCESS on success or the appropriate error. 3712 */ 3713 PJ_DECL(pj_status_t) pjsua_call_get_stream_info(pjsua_call_id call_id, 3714 unsigned med_idx, 3715 pjsua_stream_info *psi); 3716 3717 /** 3718 * Get media stream statistic for the specified media index. 3719 * 3720 * @param call_id The call identification. 3721 * @param med_idx Media stream index. 3722 * @param psi To be filled with the stream statistic. 3723 * 3724 * @return PJ_SUCCESS on success or the appropriate error. 3725 */ 3726 PJ_DECL(pj_status_t) pjsua_call_get_stream_stat(pjsua_call_id call_id, 3727 unsigned med_idx, 3728 pjsua_stream_stat *stat); 3729 3730 /** 3731 * Get media transport info for the specified media index. 3732 * 3733 * @param call_id The call identification. 3734 * @param med_idx Media stream index. 3735 * @param t To be filled with the transport info. 3736 * 3737 * @return PJ_SUCCESS on success or the appropriate error. 3738 */ 3739 PJ_DECL(pj_status_t) pjsua_call_get_transport_info(pjsua_call_id call_id, 3740 unsigned med_idx, 3741 pjmedia_transport_info *t); 3742 3743 3573 3744 3574 3745 /** … … 4448 4619 4449 4620 4450 4451 4452 4621 /** 4453 4622 * Get maxinum number of conference ports. … … 4940 5109 4941 5110 /***************************************************************************** 4942 * Video devices.4943 */4944 4945 /**4946 * Enum all video devices installed in the system.4947 *4948 * @param info Array of info to be initialized.4949 * @param count On input, specifies max elements in the array.4950 * On return, it contains actual number of elements4951 * that have been initialized.4952 *4953 * @return PJ_SUCCESS on success, or the appropriate error code.4954 */4955 PJ_DECL(pj_status_t) pjsua_vid_enum_devs(pjmedia_vid_dev_info info[],4956 unsigned *count);4957 4958 4959 /**4960 * Get currently active video devices. If video devices has not been created4961 * (for example when pjsua_start() is not called), it is possible that4962 * the function returns PJ_SUCCESS with -1 as device IDs.4963 *4964 * @param capture_dev On return it will be filled with device ID of the4965 * capture device.4966 * @param render_dev On return it will be filled with device ID of the4967 * device ID of the render device.4968 *4969 * @return PJ_SUCCESS on success, or the appropriate error code.4970 */4971 PJ_DECL(pj_status_t) pjsua_vid_get_dev(int *capture_dev, int *render_dev);4972 4973 4974 /**4975 * Select video device for the next video sessions.4976 *4977 * @param capture_dev Device ID of the capture device.4978 * @param render_dev Device ID of the render device.4979 *4980 * @return PJ_SUCCESS on success, or the appropriate error code.4981 */4982 PJ_DECL(pj_status_t) pjsua_vid_set_dev(int capture_dev, int render_dev);4983 4984 4985 /**4986 * Configure video device setting to the video device being used. If video4987 * device is currently active, the function will forward the setting to the4988 * video device instance to be applied immediately, if it supports it.4989 *4990 * The setting will be saved for future opening of the video device, if the4991 * "keep" argument is set to non-zero. If the video device is currently4992 * inactive, and the "keep" argument is false, this function will return4993 * error.4994 *4995 * Note that in case the setting is kept for future use, it will be applied4996 * to any devices, even when application has changed the video device to be4997 * used.4998 *4999 * See also #pjmedia_vid_dev_stream_set_cap() for more information about5000 * setting an video device capability.5001 *5002 * @param cap The video device setting to change.5003 * @param pval Pointer to value. Please see #pjmedia_vid_dev_cap5004 * documentation about the type of value to be5005 * supplied for each setting.5006 * @param keep Specify whether the setting is to be kept for future5007 * use.5008 *5009 * @return PJ_SUCCESS on success or the appropriate error code.5010 */5011 PJ_DECL(pj_status_t) pjsua_vid_set_setting(pjmedia_vid_dev_cap cap,5012 const void *pval,5013 pj_bool_t keep);5014 5015 /**5016 * Retrieve a video device setting. If video device is currently active,5017 * the function will forward the request to the video device. If video device5018 * is currently inactive, and if application had previously set the setting5019 * and mark the setting as kept, then that setting will be returned.5020 * Otherwise, this function will return error.5021 *5022 * @param cap The video device setting to retrieve.5023 * @param pval Pointer to receive the value.5024 * Please see #pjmedia_vid_dev_cap documentation about5025 * the type of value to be supplied for each setting.5026 *5027 * @return PJ_SUCCESS on success or the appropriate error code.5028 */5029 PJ_DECL(pj_status_t) pjsua_vid_get_setting(pjmedia_vid_dev_cap cap,5030 void *pval);5031 5032 5033 /*****************************************************************************5034 5111 * Codecs. 5035 5112 */ … … 5088 5165 const pjmedia_codec_param *param); 5089 5166 5090 /*****************************************************************************5091 * Video codecs.5092 */5093 5094 /**5095 * Enum all supported video codecs in the system.5096 *5097 * @param id Array of ID to be initialized.5098 * @param count On input, specifies max elements in the array.5099 * On return, it contains actual number of elements5100 * that have been initialized.5101 *5102 * @return PJ_SUCCESS on success, or the appropriate error code.5103 */5104 PJ_DECL(pj_status_t) pjsua_vid_enum_codecs( pjsua_codec_info id[],5105 unsigned *count );5106 5107 5108 /**5109 * Change video codec priority.5110 *5111 * @param codec_id Codec ID, which is a string that uniquely identify5112 * the codec (such as "H263/90000"). Please see pjsua5113 * manual or pjmedia codec reference for details.5114 * @param priority Codec priority, 0-255, where zero means to disable5115 * the codec.5116 *5117 * @return PJ_SUCCESS on success, or the appropriate error code.5118 */5119 PJ_DECL(pj_status_t) pjsua_vid_codec_set_priority( const pj_str_t *codec_id,5120 pj_uint8_t priority );5121 5122 5123 /**5124 * Get video codec parameters.5125 *5126 * @param codec_id Codec ID.5127 * @param param Structure to receive video codec parameters.5128 *5129 * @return PJ_SUCCESS on success, or the appropriate error code.5130 */5131 PJ_DECL(pj_status_t) pjsua_vid_codec_get_param(5132 const pj_str_t *codec_id,5133 pjmedia_vid_codec_param *param);5134 5135 5136 /**5137 * Set video codec parameters.5138 *5139 * @param codec_id Codec ID.5140 * @param param Codec parameter to set. Set to NULL to reset5141 * codec parameter to library default settings.5142 *5143 * @return PJ_SUCCESS on success, or the appropriate error code.5144 */5145 PJ_DECL(pj_status_t) pjsua_vid_codec_set_param(5146 const pj_str_t *codec_id,5147 const pjmedia_vid_codec_param *param);5148 5149 5167 5150 5168 #if DISABLED_FOR_TICKET_1185 … … 5159 5177 * @return PJ_SUCCESS on success, or the appropriate error code. 5160 5178 */ 5161 PJ_DECL(pj_status_t) 5179 PJ_DECL(pj_status_t) 5162 5180 pjsua_media_transports_create(const pjsua_transport_config *cfg); 5163 5181 … … 5176 5194 * @return PJ_SUCCESS on success, or the appropriate error code. 5177 5195 */ 5178 PJ_DECL(pj_status_t) 5196 PJ_DECL(pj_status_t) 5179 5197 pjsua_media_transports_attach( pjsua_media_transport tp[], 5180 5198 unsigned count, … … 5183 5201 5184 5202 5203 /* end of MEDIA API */ 5185 5204 /** 5186 5205 * @} … … 5188 5207 5189 5208 5190 5209 /***************************************************************************** 5210 * VIDEO API 5211 */ 5212 5213 5214 /** 5215 * @defgroup PJSUA_LIB_VIDEO PJSUA-API Video 5216 * @ingroup PJSUA_LIB 5217 * @brief Video support 5218 * @{ 5219 */ 5220 5221 /* 5222 * Video devices API 5223 */ 5224 5225 /** 5226 * Get the number of video devices installed in the system. 5227 * 5228 * @return The number of devices. 5229 */ 5230 PJ_DECL(unsigned) pjsua_vid_dev_count(void); 5231 5232 /** 5233 * Retrieve the video device info for the specified device index. 5234 * 5235 * @param id The device index. 5236 * @param vdi Device info to be initialized. 5237 * 5238 * @return PJ_SUCCESS on success, or the appropriate error code. 5239 */ 5240 PJ_DECL(pj_status_t) pjsua_vid_dev_get_info(pjmedia_vid_dev_index id, 5241 pjmedia_vid_dev_info *vdi); 5242 5243 /** 5244 * Enum all video devices installed in the system. 5245 * 5246 * @param info Array of info to be initialized. 5247 * @param count On input, specifies max elements in the array. 5248 * On return, it contains actual number of elements 5249 * that have been initialized. 5250 * 5251 * @return PJ_SUCCESS on success, or the appropriate error code. 5252 */ 5253 PJ_DECL(pj_status_t) pjsua_vid_enum_devs(pjmedia_vid_dev_info info[], 5254 unsigned *count); 5255 5256 5257 /* 5258 * Video preview API 5259 */ 5260 5261 /** 5262 * Parameters for starting video preview with pjsua_vid_preview_start(). 5263 * Application should initialize this structure with 5264 * pjsua_vid_preview_param_default(). 5265 */ 5266 typedef struct pjsua_vid_preview_param 5267 { 5268 /** 5269 * Device ID for the video renderer to be used for rendering the 5270 * capture stream for preview. 5271 */ 5272 pjmedia_vid_dev_index rend_id; 5273 } pjsua_vid_preview_param; 5274 5275 5276 /** 5277 * Start video preview window for the specified capture device. 5278 * 5279 * @param id The capture device ID where its preview will be 5280 * started. 5281 * @param prm Optional video preview parameters. Specify NULL 5282 * to use default values. 5283 * 5284 * @return PJ_SUCCESS on success, or the appropriate error code. 5285 */ 5286 PJ_DECL(pj_status_t) pjsua_vid_preview_start(pjmedia_vid_dev_index id, 5287 pjsua_vid_preview_param *prm); 5288 5289 /** 5290 * Get the preview window handle associated with the capture device, if any. 5291 * 5292 * @param id The capture device ID. 5293 * 5294 * @return The window ID of the preview window for the 5295 * specified capture device ID, or NULL if preview 5296 * does not exist. 5297 */ 5298 PJ_DECL(pjsua_vid_win_id) pjsua_vid_preview_get_win(pjmedia_vid_dev_index id); 5299 5300 /** 5301 * Stop video preview. 5302 * 5303 * @param id The capture device ID. 5304 * 5305 * @return PJ_SUCCESS on success, or the appropriate error code. 5306 */ 5307 PJ_DECL(pj_status_t) pjsua_vid_preview_stop(pjmedia_vid_dev_index id); 5308 5309 5310 /* 5311 * Video window manipulation API. 5312 */ 5313 5314 /** 5315 * This structure describes video window info. 5316 */ 5317 typedef struct pjsua_vid_win_info 5318 { 5319 /** 5320 * Window show status. The window is hidden if false. 5321 */ 5322 pj_bool_t show; 5323 5324 /** 5325 * Window position. 5326 */ 5327 pjmedia_coord pos; 5328 5329 /** 5330 * Window size. 5331 */ 5332 pjmedia_rect_size size; 5333 5334 } pjsua_vid_win_info; 5335 5336 5337 /** 5338 * Get window info. 5339 * 5340 * @param wid The video window ID. 5341 * @param wi The video window info to be initialized. 5342 * 5343 * @return PJ_SUCCESS on success, or the appropriate error code. 5344 */ 5345 PJ_DECL(pj_status_t) pjsua_vid_win_get_info(pjsua_vid_win_id wid, 5346 pjsua_vid_win_info *wi); 5347 5348 /** 5349 * Show or hide window. 5350 * 5351 * @param wid The video window ID. 5352 * @param show Set to PJ_TRUE to show the window, PJ_FALSE to 5353 * hide the window. 5354 * 5355 * @return PJ_SUCCESS on success, or the appropriate error code. 5356 */ 5357 PJ_DECL(pj_status_t) pjsua_vid_win_set_show(pjsua_vid_win_id wid, 5358 pj_bool_t show); 5359 5360 /** 5361 * Set video window position. 5362 * 5363 * @param wid The video window ID. 5364 * @param pos The window position. 5365 * 5366 * @return PJ_SUCCESS on success, or the appropriate error code. 5367 */ 5368 PJ_DECL(pj_status_t) pjsua_vid_win_set_pos(pjsua_vid_win_id wid, 5369 const pjmedia_coord *pos); 5370 5371 /** 5372 * Resize window. 5373 * 5374 * @param wid The video window ID. 5375 * @param size The new window size. 5376 * 5377 * @return PJ_SUCCESS on success, or the appropriate error code. 5378 */ 5379 PJ_DECL(pj_status_t) pjsua_vid_win_set_size(pjsua_vid_win_id wid, 5380 const pjmedia_rect_size *size); 5381 5382 5383 5384 /* 5385 * Video codecs API 5386 */ 5387 5388 /** 5389 * Enum all supported video codecs in the system. 5390 * 5391 * @param id Array of ID to be initialized. 5392 * @param count On input, specifies max elements in the array. 5393 * On return, it contains actual number of elements 5394 * that have been initialized. 5395 * 5396 * @return PJ_SUCCESS on success, or the appropriate error code. 5397 */ 5398 PJ_DECL(pj_status_t) pjsua_vid_enum_codecs( pjsua_codec_info id[], 5399 unsigned *count ); 5400 5401 5402 /** 5403 * Change video codec priority. 5404 * 5405 * @param codec_id Codec ID, which is a string that uniquely identify 5406 * the codec (such as "H263/90000"). Please see pjsua 5407 * manual or pjmedia codec reference for details. 5408 * @param priority Codec priority, 0-255, where zero means to disable 5409 * the codec. 5410 * 5411 * @return PJ_SUCCESS on success, or the appropriate error code. 5412 */ 5413 PJ_DECL(pj_status_t) pjsua_vid_codec_set_priority( const pj_str_t *codec_id, 5414 pj_uint8_t priority ); 5415 5416 5417 /** 5418 * Get video codec parameters. 5419 * 5420 * @param codec_id Codec ID. 5421 * @param param Structure to receive video codec parameters. 5422 * 5423 * @return PJ_SUCCESS on success, or the appropriate error code. 5424 */ 5425 PJ_DECL(pj_status_t) pjsua_vid_codec_get_param( 5426 const pj_str_t *codec_id, 5427 pjmedia_vid_codec_param *param); 5428 5429 5430 /** 5431 * Set video codec parameters. 5432 * 5433 * @param codec_id Codec ID. 5434 * @param param Codec parameter to set. Set to NULL to reset 5435 * codec parameter to library default settings. 5436 * 5437 * @return PJ_SUCCESS on success, or the appropriate error code. 5438 */ 5439 PJ_DECL(pj_status_t) pjsua_vid_codec_set_param( 5440 const pj_str_t *codec_id, 5441 const pjmedia_vid_codec_param *param); 5442 5443 5444 5445 /* end of VIDEO API */ 5191 5446 /** 5192 5447 * @} 5193 5448 */ 5194 5449 5450 5451 /** 5452 * @} 5453 */ 5454 5195 5455 PJ_END_DECL 5196 5456
Note: See TracChangeset
for help on using the changeset viewer.
