diff --git a/include/linphone/core.h b/include/linphone/core.h index ce0e774e0..ded8e3949 100644 --- a/include/linphone/core.h +++ b/include/linphone/core.h @@ -165,7 +165,8 @@ typedef struct _LinphoneCoreVTable{ LinphoneCoreNotifyPresenceReceivedCb notify_presence_received; /**< Notify received presence events*/ LinphoneCoreNotifyPresenceReceivedForUriOrTelCb notify_presence_received_for_uri_or_tel; /**< Notify received presence events*/ LinphoneCoreNewSubscriptionRequestedCb new_subscription_requested; /**< Notify about pending presence subscription request */ - LINPHONE_DEPRECATED LinphoneCoreAuthInfoRequestedCb auth_info_requested; /**< @deprecated Use authentication_requested instead. Ask the application some authentication information */ + LINPHONE_DEPRECATED LinphoneCoreAuthInfoRequestedCb auth_info_requested; /** @brief Ask the application some authentication information. + @deprecated Use authentication_requested instead. Deprecated since 2016-09-21 */ LinphoneCoreAuthenticationRequestedCb authentication_requested; /**< Ask the application some authentication information */ LinphoneCoreCallLogUpdatedCb call_log_updated; /**< Notifies that call log list has been updated */ LinphoneCoreMessageReceivedCb message_received; /**< a message is received, can be text or external body*/ @@ -181,11 +182,16 @@ typedef struct _LinphoneCoreVTable{ LinphoneCoreSubscriptionStateChangedCb subscription_state_changed; /** A text message has been received */ - LINPHONE_DEPRECATED LinphoneCoreFileTransferRecvCb file_transfer_recv; /**< @deprecated Callback to store file received attached to a #LinphoneChatMessage */ - LINPHONE_DEPRECATED LinphoneCoreFileTransferSendCb file_transfer_send; /**< @deprecated Callback to collect file chunk to be sent for a #LinphoneChatMessage */ - LINPHONE_DEPRECATED LinphoneCoreFileTransferProgressIndicationCb file_transfer_progress_indication; /**< @deprecated Callback to indicate file transfer progress */ + LinphoneCoreConfiguringStatusCb configuring_status; /**< Notifies configuring status changes + @deprecated Deprecated since 2015-11-19. */ + LINPHONE_DEPRECATED LinphoneCoreTextMessageReceivedCb text_received; /**< @brief A text message has been received. + @deprecated Use #message_received instead. Deprecated since 2015-11-19. */ + LINPHONE_DEPRECATED LinphoneCoreFileTransferRecvCb file_transfer_recv; /**< @brief Callback to store file received attached to a #LinphoneChatMessage. + @deprecated Deprecated since 2015-11-19. */ + LINPHONE_DEPRECATED LinphoneCoreFileTransferSendCb file_transfer_send; /**< @brief Callback to collect file chunk to be sent for a #LinphoneChatMessage. + @deprecated Deprecated since 2015-11-19. */ + LINPHONE_DEPRECATED LinphoneCoreFileTransferProgressIndicationCb file_transfer_progress_indication; /**< @brief Callback to indicate file transfer progress. + @deprecated Deprecated since 2015-11-19. */ LinphoneCoreNetworkReachableCb network_reachable; /**< Callback to report IP network status (I.E up/down )*/ LinphoneCoreLogCollectionUploadStateChangedCb log_collection_upload_state_changed; /**< Callback to upload collected logs */ LinphoneCoreLogCollectionUploadProgressIndicationCb log_collection_upload_progress_indication; /**< Callback to indicate log collection upload progress */ @@ -886,13 +892,15 @@ LINPHONE_PUBLIC const char *linphone_core_get_version(void); LINPHONE_PUBLIC const char *linphone_core_get_user_agent(LinphoneCore *lc); /** - * @deprecated 2016-12-20: Use #linphone_core_get_user_agent instead. + * @deprecated Use #linphone_core_get_user_agent() instead. + * Deprecated since 2015-11-19. * @donotwrap **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED const char *linphone_core_get_user_agent_name(void); /** - * @deprecated 2016-12-20: Use #linphone_core_get_user_agent instead. + * @deprecated Use #linphone_core_get_user_agent instead. + * Deprecated since 2015-11-19. * @donotwrap **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED const char *linphone_core_get_user_agent_version(void); @@ -910,8 +918,8 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED const char *linphone_core_get_user_agent_ver * @param vtable a LinphoneCoreVTable structure holding your application callbacks * @param config_path a path to a config file. If it does not exists it will be created. * The config file is used to store all settings, call logs, friends, proxies... so that all these settings - * become persistent over the life of the LinphoneCore object. - * It is allowed to set a NULL config file. In that case LinphoneCore will not store any settings. + * become persistent over the life of the LinphoneCore object. + * It is allowed to set a NULL config file. In that case LinphoneCore will not store any settings. * @param factory_config_path a path to a read-only config file that can be used to * to store hard-coded preference such as proxy settings or internal preferences. * The settings in this factory file always override the one in the normal config file. @@ -919,7 +927,7 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED const char *linphone_core_get_user_agent_ver * @param userdata an opaque user pointer that can be retrieved at any time (for example in * callbacks) using linphone_core_get_user_data(). * @see linphone_core_new_with_config - * @deprecated 2017-01-12: Use linphone_factory_create_core() instead. + * @deprecated Use #linphone_factory_create_core() instead. Deprecated since 2017-01-12. * @donotwrap **/ LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_core_new(const LinphoneCoreVTable *vtable, @@ -936,7 +944,7 @@ LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_core_new(const Linpho * @param userdata an opaque user pointer that can be retrieved at any time (for example in * callbacks) using linphone_core_get_user_data(). * @see linphone_core_new - * @deprecated 2017-01-12: Use linphone_factory_create_core_with_config() instead. + * @deprecated Use #linphone_factory_create_core_with_config() instead. Deprecated since 2017-01-12. * @donotwrap **/ LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_core_new_with_config(const LinphoneCoreVTable *vtable, LpConfig *config, void *userdata); @@ -987,7 +995,7 @@ LINPHONE_PUBLIC void linphone_core_iterate(LinphoneCore *lc); * add a listener to be notified of linphone core events. Once events are received, registered vtable are invoked in order. * @param vtable a LinphoneCoreVTable structure holding your application callbacks. Object is owned by linphone core until linphone_core_remove_listener. * @param lc object - * @deprecated Use linphone_core_add_callbacks() instead. + * @deprecated Use linphone_core_add_callbacks() instead. Deprecated since 2017-01-12. * @donotwrap */ LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_add_listener(LinphoneCore *lc, LinphoneCoreVTable *vtable); @@ -1006,7 +1014,7 @@ LINPHONE_PUBLIC void linphone_core_add_callbacks(LinphoneCore *lc, LinphoneCoreC * remove a listener registred by linphone_core_add_listener. * @param lc object * @param vtable a LinphoneCoreVTable structure holding your application callbacks. - * @deprecated Use linphone_core_remove_callbacks() instead. + * @deprecated Use linphone_core_remove_callbacks() instead. Deprecated since 2017-01-12. * @donotwrap */ LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_remove_listener(LinphoneCore *lc, const LinphoneCoreVTable *vtable); @@ -1086,7 +1094,8 @@ LINPHONE_PUBLIC LinphoneCall * linphone_core_invite_with_params(LinphoneCore *lc LINPHONE_PUBLIC LinphoneCall * linphone_core_invite_address_with_params(LinphoneCore *lc, const LinphoneAddress *addr, const LinphoneCallParams *params); /** - * Performs a simple call transfer to the specified destination. + * @brief Performs a simple call transfer to the specified destination. + * * The remote endpoint is expected to issue a new call to the specified destination. * The current call remains active and thus can be later paused or terminated. * It is possible to follow the progress of the transfer provided that transferee sends notification about it. @@ -1097,12 +1106,13 @@ LINPHONE_PUBLIC LinphoneCall * linphone_core_invite_address_with_params(Linphone * @param[in] refer_to The destination the call is to be refered to * @return 0 on success, -1 on failure * @ingroup call_control - * @deprecated Use linphone_call_transfer() instead + * @deprecated Use #linphone_call_transfer() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_transfer_call(LinphoneCore *lc, LinphoneCall *call, const char *refer_to); /** - * Transfers a call to destination of another running call. This is used for "attended transfer" scenarios. + * @brief Transfers a call to destination of another running call. This is used for "attended transfer" scenarios. + * * The transfered call is supposed to be in paused state, so that it is able to accept the transfer immediately. * The destination call is a call previously established to introduce the transfered person. * This method will send a transfer request to the transfered person. The phone of the transfered is then @@ -1116,12 +1126,13 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_transfer_call(L * @param[in] dest A running call whose remote person will receive the transfer * @return 0 on success, -1 on failure * @ingroup call_control - * @deprecated Use linphone_call_transfer_to_another() instead + * @deprecated Use #linphone_call_transfer_to_another() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_transfer_call_to_another(LinphoneCore *lc, LinphoneCall *call, LinphoneCall *dest); /** - * Start a new call as a consequence of a transfer request received from a call. + * @brief Start a new call as a consequence of a transfer request received from a call. + * * This function is for advanced usage: the execution of transfers is automatically managed by the LinphoneCore. However if an application * wants to have control over the call parameters for the new call, it should call this function immediately during the LinphoneCallRefered notification. * @see LinphoneCoreVTable::call_state_changed @@ -1136,7 +1147,8 @@ LINPHONE_PUBLIC LinphoneCall * linphone_core_start_refered_call(LinphoneCore *lc #define linphone_core_inc_invite_pending(lc) linphone_core_is_incoming_invite_pending(lc) /** - * Tells whether there is an incoming invite pending. + * @brief Tells whether there is an incoming invite pending. + * * @ingroup call_control * @param[in] lc LinphoneCore object * @return A boolean telling whether an incoming invite is pending or not. @@ -1160,7 +1172,7 @@ LINPHONE_PUBLIC bool_t linphone_core_in_call(const LinphoneCore *lc); LINPHONE_PUBLIC LinphoneCall *linphone_core_get_current_call(const LinphoneCore *lc); /** - * Accept an incoming call. + * @brief Accept an incoming call. * * Basically the application is notified of incoming calls within the * call_state_changed callback of the #LinphoneCoreVTable structure, where it will receive @@ -1170,12 +1182,12 @@ LINPHONE_PUBLIC LinphoneCall *linphone_core_get_current_call(const LinphoneCore * @param[in] call The LinphoneCall object representing the call to be answered * @return 0 on success, -1 on failure * @ingroup call_control - * @deprecated Use linphone_call_accept() instead + * @deprecated Use #linphone_call_accept() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_call(LinphoneCore *lc, LinphoneCall *call); /** - * Accept an incoming call, with parameters. + * @brief Accept an incoming call, with parameters. * * Basically the application is notified of incoming calls within the * call_state_changed callback of the #LinphoneCoreVTable structure, where it will receive @@ -1187,12 +1199,13 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_call(Lin * @param[in] params The specific parameters for this call, for example whether video is accepted or not. Use NULL to use default parameters * @return 0 on success, -1 on failure * @ingroup call_control - * @deprecated Use linphone_call_accept_with_params() instead + * @deprecated Use #linphone_call_accept_with_params() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_call_with_params(LinphoneCore *lc, LinphoneCall *call, const LinphoneCallParams *params); /** - * When receiving an incoming, accept to start a media session as early-media. + * @brief When receiving an incoming, accept to start a media session as early-media. + * * This means the call is not accepted but audio & video streams can be established if the remote party supports early media. * However, unlike after call acceptance, mic and camera input are not sent during early-media, though received audio & video are played normally. * The call can then later be fully accepted using linphone_core_accept_call() or linphone_core_accept_call_with_params(). @@ -1201,29 +1214,31 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_call_wit * @param[in] params The call parameters to use (can be NULL) * @return 0 if successful, -1 otherwise * @ingroup call_control - * @deprecated Use linphone_call_accept_early_media_with_params() instead + * @deprecated Use linphone_call_accept_early_media_with_params() instead. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_early_media_with_params(LinphoneCore* lc, LinphoneCall* call, const LinphoneCallParams* params); /** - * Accept an early media session for an incoming call. + * @brief Accept an early media session for an incoming call. + * * This is identical as calling linphone_core_accept_early_media_with_params() with NULL call parameters. * @param[in] lc LinphoneCore object * @param[in] call The incoming call to accept * @return 0 if successful, -1 otherwise * @ingroup call_control * @see linphone_core_accept_early_media_with_params() - * @deprecated Use linphone_call_accept_early_media() instead + * @deprecated Use #linphone_call_accept_early_media() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_early_media(LinphoneCore* lc, LinphoneCall* call); /** - * Terminates a call. + * @brief Terminates a call. + * * @param[in] lc LinphoneCore object * @param[in] call The LinphoneCall object representing the call to be terminated * @return 0 on success, -1 on failure * @ingroup call_control - * @deprecated Use linphone_call_terminate() instead + * @deprecated Use #linphone_call_terminate() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_terminate_call(LinphoneCore *lc, LinphoneCall *call); @@ -1234,18 +1249,18 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_terminate_call( * @param[in] redirect_uri The URI to redirect the call to * @return 0 if successful, -1 on error. * @ingroup call_control - * @deprecated Use linphone_call_redirect() instead + * @deprecated Use #linphone_call_redirect() instead. Deprecated since 2017-02-13. */ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_redirect_call(LinphoneCore *lc, LinphoneCall *call, const char *redirect_uri); /** - * Decline a pending incoming call, with a reason. - * @param[in] lc LinphoneCore object - * @param[in] call The LinphoneCall to decline, must be in the IncomingReceived state - * @param[in] reason The reason for rejecting the call: LinphoneReasonDeclined or LinphoneReasonBusy + * @brief Decline a pending incoming call, with a reason. + * @param[in] lc #LinphoneCore object + * @param[in] call The #LinphoneCall to decline, must be in the IncomingReceived state + * @param[in] reason The reason for rejecting the call: #LinphoneReasonDeclined or #LinphoneReasonBusy * @return 0 on success, -1 on failure * @ingroup call_control - * @deprecated Use linphone_call_decline() instead + * @deprecated Use #linphone_call_decline() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_decline_call(LinphoneCore *lc, LinphoneCall * call, LinphoneReason reason); @@ -1258,15 +1273,16 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_decline_call(Li LINPHONE_PUBLIC LinphoneStatus linphone_core_terminate_all_calls(LinphoneCore *lc); /** - * Pauses the call. If a music file has been setup using linphone_core_set_play_file(), + * @biref Pauses the call. If a music file has been setup using linphone_core_set_play_file(), * this file will be played to the remote user. + * * The only way to resume a paused call is to call linphone_core_resume_call(). * @param[in] lc LinphoneCore object * @param[in] call The call to pause * @return 0 on success, -1 on failure * @ingroup call_control * @see linphone_core_resume_call() - * @deprecated Use linphone_call_pause() instead + * @deprecated Use #linphone_call_pause() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_pause_call(LinphoneCore *lc, LinphoneCall *call); @@ -1279,19 +1295,21 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_pause_call(Linp LINPHONE_PUBLIC LinphoneStatus linphone_core_pause_all_calls(LinphoneCore *lc); /** - * Resumes a call. + * @brief Resumes a call. + * * The call needs to have been paused previously with linphone_core_pause_call(). * @param[in] lc LinphoneCore object * @param[in] call The call to resume * @return 0 on success, -1 on failure * @ingroup call_control * @see linphone_core_pause_call() - * @deprecated Use linphone_call_resume() instead + * @deprecated Use #linphone_call_resume() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_resume_call(LinphoneCore *lc, LinphoneCall *call); /** - * Updates a running call according to supplied call parameters or parameters changed in the LinphoneCore. + * @brief Updates a running call according to supplied call parameters or parameters changed in the LinphoneCore. + * * In this version this is limited to the following use cases: * - setting up/down the video stream according to the video parameter of the LinphoneCallParams (see linphone_call_params_enable_video() ). * - changing the size of the transmitted video after calling linphone_core_set_preferred_video_size() @@ -1304,7 +1322,7 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_resume_call(Lin * @param[in] params The new call parameters to use (may be NULL) * @return 0 if successful, -1 otherwise. * @ingroup call_control - * @deprecated Use linphone_call_update() instead + * @deprecated Use #linphone_call_update() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_update_call(LinphoneCore *lc, LinphoneCall *call, const LinphoneCallParams *params); @@ -1333,7 +1351,7 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_update_call(Lin LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_defer_call_update(LinphoneCore *lc, LinphoneCall *call); /** - * Accept call modifications initiated by other end. + * @brief Accept call modifications initiated by other end. * * This call may be performed in response to a #LinphoneCallUpdatedByRemote state notification. * When such notification arrives, the application can decide to call linphone_core_defer_update_call() so that it can @@ -1350,7 +1368,7 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_defer_call_upda * @param[in] params A LinphoneCallParams object describing the call parameters to accept * @return 0 if successful, -1 otherwise (actually when this function call is performed outside ot #LinphoneCallUpdatedByRemote state) * @ingroup call_control - * @deprecated Use linphone_call_accept_update() instead + * @deprecated Use #linphone_call_accept_update() instead. Deprecated since 2017-02-13. **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_accept_call_update(LinphoneCore *lc, LinphoneCall *call, const LinphoneCallParams *params); @@ -1386,13 +1404,13 @@ LINPHONE_PUBLIC LinphoneCall *linphone_core_get_call_by_remote_address2(const Li /** - * Send the specified dtmf. + * @brief Send the specified dtmf. * - * @ingroup media_parameters - * @deprecated Use #linphone_call_send_dtmf instead. * This function only works during calls. The dtmf is automatically played to the user. * @param lc The LinphoneCore object * @param dtmf The dtmf name specified as a char, such as '0', '#' etc... + * @deprecated Use #linphone_call_send_dtmf instead. Deprecated since 2015-11-23. + * @ingroup media_parameters * @donotwrap **/ LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_core_send_dtmf(LinphoneCore *lc, char dtmf);