From cfbb66457fab1727c10208581fe283f6a4adf2b5 Mon Sep 17 00:00:00 2001 From: Ghislain MARY Date: Fri, 15 Sep 2017 11:34:39 +0200 Subject: [PATCH] Add a specific header for the chat room API. --- include/CMakeLists.txt | 1 + include/linphone/api/c-api.h | 1 + include/linphone/api/c-chat-room.h | 249 +++++++++++++++++++++++++++++ include/linphone/api/c-types.h | 1 + include/linphone/chat.h | 206 +----------------------- 5 files changed, 254 insertions(+), 204 deletions(-) create mode 100644 include/linphone/api/c-chat-room.h diff --git a/include/CMakeLists.txt b/include/CMakeLists.txt index cd1e77d89..ecedd8a55 100644 --- a/include/CMakeLists.txt +++ b/include/CMakeLists.txt @@ -76,6 +76,7 @@ set(ROOT_HEADER_FILES set(C_API_HEADER_FILES c-address.h c-api.h + c-chat-room.h c-event-log.h c-participant.h c-types.h diff --git a/include/linphone/api/c-api.h b/include/linphone/api/c-api.h index fab3520bd..009498b29 100644 --- a/include/linphone/api/c-api.h +++ b/include/linphone/api/c-api.h @@ -20,6 +20,7 @@ #define _C_API_H_ #include "linphone/api/c-address.h" +#include "linphone/api/c-chat-room.h" #include "linphone/api/c-event-log.h" #include "linphone/api/c-participant.h" diff --git a/include/linphone/api/c-chat-room.h b/include/linphone/api/c-chat-room.h new file mode 100644 index 000000000..5cf75e77d --- /dev/null +++ b/include/linphone/api/c-chat-room.h @@ -0,0 +1,249 @@ +/* + * c-chat-room.h + * Copyright (C) 2017 Belledonne Communications SARL + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +#ifndef _C_CHAT_ROOM_H_ +#define _C_CHAT_ROOM_H_ + +#include "linphone/api/c-types.h" + +// ============================================================================= + +#ifdef __cplusplus + extern "C" { +#endif // ifdef __cplusplus + +/** + * @addtogroup chatroom + * @{ + */ + +/** + * Acquire a reference to the chat room. + * @param[in] cr The chat room. + * @return The same chat room. +**/ +LINPHONE_PUBLIC LinphoneChatRoom *linphone_chat_room_ref(LinphoneChatRoom *cr); + +/** + * Release reference to the chat room. + * @param[in] cr The chat room. +**/ +LINPHONE_PUBLIC void linphone_chat_room_unref(LinphoneChatRoom *cr); + +/** + * Retrieve the user pointer associated with the chat room. + * @param[in] cr The chat room. + * @return The user pointer associated with the chat room. +**/ +LINPHONE_PUBLIC void *linphone_chat_room_get_user_data(const LinphoneChatRoom *cr); + +/** + * Assign a user pointer to the chat room. + * @param[in] cr The chat room. + * @param[in] ud The user pointer to associate with the chat room. +**/ +LINPHONE_PUBLIC void linphone_chat_room_set_user_data(LinphoneChatRoom *cr, void *ud); + +/** + * Create a message attached to a dedicated chat room; + * @param cr the chat room. + * @param message text message, NULL if absent. + * @return a new #LinphoneChatMessage + */ +LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_message(LinphoneChatRoom *cr,const char* message); + +/** + * Create a message attached to a dedicated chat room; + * @param cr the chat room. + * @param message text message, NULL if absent. + * @param external_body_url the URL given in external body or NULL. + * @param state the LinphoneChatMessage.State of the message. + * @param time the time_t at which the message has been received/sent. + * @param is_read TRUE if the message should be flagged as read, FALSE otherwise. + * @param is_incoming TRUE if the message has been received, FALSE otherwise. + * @return a new #LinphoneChatMessage + */ +LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_message_2(LinphoneChatRoom *cr, const char* message, const char* external_body_url, LinphoneChatMessageState state, time_t time, bool_t is_read, bool_t is_incoming); + + /** + * Create a message attached to a dedicated chat room with a particular content. + * Use #linphone_chat_room_send_message to initiate the transfer + * @param cr the chat room. + * @param initial_content #LinphoneContent initial content. #LinphoneCoreVTable.file_transfer_send is invoked later to notify file transfer progress and collect next chunk of the message if LinphoneContent.data is NULL. + * @return a new #LinphoneChatMessage + */ +LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_file_transfer_message(LinphoneChatRoom *cr, const LinphoneContent* initial_content); + +/** + * get peer address \link linphone_core_get_chat_room() associated to \endlink this #LinphoneChatRoom + * @param cr #LinphoneChatRoom object + * @return #LinphoneAddress peer address + */ +LINPHONE_PUBLIC const LinphoneAddress* linphone_chat_room_get_peer_address(LinphoneChatRoom *cr); + +/** + * Send a message to peer member of this chat room. + * @deprecated Use linphone_chat_room_send_chat_message() instead. + * @param cr #LinphoneChatRoom object + * @param msg message to be sent + * @donotwrap + */ +LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_send_message(LinphoneChatRoom *cr, const char *msg); + +/** + * Send a message to peer member of this chat room. + * @param cr #LinphoneChatRoom object + * @param msg #LinphoneChatMessage message to be sent + * @param status_cb LinphoneChatMessageStateChangeCb status callback invoked when message is delivered or could not be delivered. May be NULL + * @param ud user data for the status cb. + * @deprecated Use linphone_chat_room_send_chat_message() instead. + * @note The LinphoneChatMessage must not be destroyed until the the callback is called. + * The LinphoneChatMessage reference is transfered to the function and thus doesn't need to be unref'd by the application. + * @donotwrap + */ +LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_send_message2(LinphoneChatRoom *cr, LinphoneChatMessage* msg,LinphoneChatMessageStateChangedCb status_cb,void* ud); + +/** + * Send a message to peer member of this chat room. + * @param[in] cr LinphoneChatRoom object + * @param[in] msg LinphoneChatMessage object + * The state of the message sending will be notified via the callbacks defined in the LinphoneChatMessageCbs object that can be obtained + * by calling linphone_chat_message_get_callbacks(). + * The LinphoneChatMessage reference is transfered to the function and thus doesn't need to be unref'd by the application. + * @donotwrap + */ +LINPHONE_PUBLIC void linphone_chat_room_send_chat_message(LinphoneChatRoom *cr, LinphoneChatMessage *msg); + +/** + * Mark all messages of the conversation as read + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. + */ +LINPHONE_PUBLIC void linphone_chat_room_mark_as_read(LinphoneChatRoom *cr); + +/** + * Delete a message from the chat room history. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. + * @param[in] msg The #LinphoneChatMessage object to remove. + */ + +LINPHONE_PUBLIC void linphone_chat_room_delete_message(LinphoneChatRoom *cr, LinphoneChatMessage *msg); + +/** + * Delete all messages from the history + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. + */ +LINPHONE_PUBLIC void linphone_chat_room_delete_history(LinphoneChatRoom *cr); + +/** + * Gets the number of messages in a chat room. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which size has to be computed + * @return the number of messages. + */ +LINPHONE_PUBLIC int linphone_chat_room_get_history_size(LinphoneChatRoom *cr); + +/** + * Gets nb_message most recent messages from cr chat room, sorted from oldest to most recent. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which messages should be retrieved + * @param[in] nb_message Number of message to retrieve. 0 means everything. + * @return \bctbx_list{LinphoneChatMessage} + */ +LINPHONE_PUBLIC bctbx_list_t *linphone_chat_room_get_history(LinphoneChatRoom *cr,int nb_message); + +/** + * Gets the partial list of messages in the given range, sorted from oldest to most recent. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which messages should be retrieved + * @param[in] begin The first message of the range to be retrieved. History most recent message has index 0. + * @param[in] end The last message of the range to be retrieved. History oldest message has index of history size - 1 (use #linphone_chat_room_get_history_size to retrieve history size) + * @return \bctbx_list{LinphoneChatMessage} + */ +LINPHONE_PUBLIC bctbx_list_t *linphone_chat_room_get_history_range(LinphoneChatRoom *cr, int begin, int end); + +LINPHONE_PUBLIC LinphoneChatMessage * linphone_chat_room_find_message(LinphoneChatRoom *cr, const char *message_id); + +/** + * Notifies the destination of the chat message being composed that the user is typing a new message. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which a new message is being typed. + */ +LINPHONE_PUBLIC void linphone_chat_room_compose(LinphoneChatRoom *cr); + +/** + * Tells whether the remote is currently composing a message. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. + * @return TRUE if the remote is currently composing a message, FALSE otherwise. + */ +LINPHONE_PUBLIC bool_t linphone_chat_room_is_remote_composing(const LinphoneChatRoom *cr); + +/** + * Gets the number of unread messages in the chatroom. + * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. + * @return the number of unread messages. + */ +LINPHONE_PUBLIC int linphone_chat_room_get_unread_messages_count(LinphoneChatRoom *cr); + +/** + * Returns back pointer to #LinphoneCore object. +**/ +LINPHONE_PUBLIC LinphoneCore* linphone_chat_room_get_core(const LinphoneChatRoom *cr); + +/** + * When realtime text is enabled #linphone_call_params_realtime_text_enabled, #LinphoneCoreIsComposingReceivedCb is call everytime a char is received from peer. + * At the end of remote typing a regular #LinphoneChatMessage is received with committed data from #LinphoneCoreMessageReceivedCb. + * @param[in] cr #LinphoneChatRoom object + * @returns RFC 4103/T.140 char + */ +LINPHONE_PUBLIC uint32_t linphone_chat_room_get_char(const LinphoneChatRoom *cr); + +/** + * Returns true if lime is available for given peer + * + * @return true if zrtp secrets have already been shared and ready to use + */ +LINPHONE_PUBLIC bool_t linphone_chat_room_lime_available(LinphoneChatRoom *cr); + +/** + * get Curent Call associated to this chatroom if any + * To commit a message, use #linphone_chat_room_send_message + * @param[in] room LinphoneChatRomm + * @returns LinphoneCall or NULL. + */ +LINPHONE_PUBLIC LinphoneCall *linphone_chat_room_get_call(const LinphoneChatRoom *room); + +/** + * Returns back pointer to #LinphoneCore object. + * @deprecated use linphone_chat_room_get_core() + * @donotwrap +**/ +LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneCore* linphone_chat_room_get_lc(const LinphoneChatRoom *cr); + +/** + * Destroy a LinphoneChatRoom. + * @param cr #LinphoneChatRoom object + * @deprecated Use linphone_chat_room_unref() instead. + * @donotwrap + */ +LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_destroy(LinphoneChatRoom *cr); + +/** + * @} + */ + +#ifdef __cplusplus + } +#endif // ifdef __cplusplus + +#endif // ifndef _C_CHAT_ROOM_H_ diff --git a/include/linphone/api/c-types.h b/include/linphone/api/c-types.h index 288564328..3fea38e86 100644 --- a/include/linphone/api/c-types.h +++ b/include/linphone/api/c-types.h @@ -75,6 +75,7 @@ typedef struct _LinphoneAddress LinphoneAddress; typedef struct _LinphoneCall LinphoneCall; typedef struct _LinphoneCallEvent LinphoneCallEvent; +typedef struct _LinphoneChatRoom LinphoneChatRoom; typedef struct _LinphoneConferenceEvent LinphoneConferenceEvent; typedef struct _LinphoneConferenceParticipantEvent LinphoneConferenceParticipantEvent; typedef struct _LinphoneEventLog LinphoneEventLog; diff --git a/include/linphone/chat.h b/include/linphone/chat.h index a3e581064..0660003b5 100644 --- a/include/linphone/chat.h +++ b/include/linphone/chat.h @@ -23,6 +23,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. #include "linphone/callbacks.h" #include "linphone/types.h" +#include "linphone/api/c-types.h" +#include "linphone/api/c-chat-room.h" #ifdef __cplusplus @@ -34,202 +36,6 @@ extern "C" { * @{ */ -/** - * Destroy a LinphoneChatRoom. - * @param cr #LinphoneChatRoom object - * @deprecated Use linphone_chat_room_unref() instead. - * @donotwrap - */ -LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_destroy(LinphoneChatRoom *cr); -/** - * Create a message attached to a dedicated chat room; - * @param cr the chat room. - * @param message text message, NULL if absent. - * @return a new #LinphoneChatMessage - */ -LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_message(LinphoneChatRoom *cr,const char* message); -/** - * Create a message attached to a dedicated chat room; - * @param cr the chat room. - * @param message text message, NULL if absent. - * @param external_body_url the URL given in external body or NULL. - * @param state the LinphoneChatMessage.State of the message. - * @param time the time_t at which the message has been received/sent. - * @param is_read TRUE if the message should be flagged as read, FALSE otherwise. - * @param is_incoming TRUE if the message has been received, FALSE otherwise. - * @return a new #LinphoneChatMessage - */ -LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_message_2(LinphoneChatRoom *cr, const char* message, const char* external_body_url, LinphoneChatMessageState state, time_t time, bool_t is_read, bool_t is_incoming); - -/** - * Acquire a reference to the chat room. - * @param[in] cr The chat room. - * @return The same chat room. -**/ -LINPHONE_PUBLIC LinphoneChatRoom *linphone_chat_room_ref(LinphoneChatRoom *cr); - -/** - * Release reference to the chat room. - * @param[in] cr The chat room. -**/ -LINPHONE_PUBLIC void linphone_chat_room_unref(LinphoneChatRoom *cr); - -/** - * Retrieve the user pointer associated with the chat room. - * @param[in] cr The chat room. - * @return The user pointer associated with the chat room. -**/ -LINPHONE_PUBLIC void *linphone_chat_room_get_user_data(const LinphoneChatRoom *cr); - -/** - * Assign a user pointer to the chat room. - * @param[in] cr The chat room. - * @param[in] ud The user pointer to associate with the chat room. -**/ -LINPHONE_PUBLIC void linphone_chat_room_set_user_data(LinphoneChatRoom *cr, void *ud); - - /** - * Create a message attached to a dedicated chat room with a particular content. - * Use #linphone_chat_room_send_message to initiate the transfer - * @param cr the chat room. - * @param initial_content #LinphoneContent initial content. #LinphoneCoreVTable.file_transfer_send is invoked later to notify file transfer progress and collect next chunk of the message if LinphoneContent.data is NULL. - * @return a new #LinphoneChatMessage - */ -LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_file_transfer_message(LinphoneChatRoom *cr, const LinphoneContent* initial_content); - -/** - * get peer address \link linphone_core_get_chat_room() associated to \endlink this #LinphoneChatRoom - * @param cr #LinphoneChatRoom object - * @return #LinphoneAddress peer address - */ -LINPHONE_PUBLIC const LinphoneAddress* linphone_chat_room_get_peer_address(LinphoneChatRoom *cr); - -/** - * Send a message to peer member of this chat room. - * @deprecated Use linphone_chat_room_send_chat_message() instead. - * @param cr #LinphoneChatRoom object - * @param msg message to be sent - * @donotwrap - */ -LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_send_message(LinphoneChatRoom *cr, const char *msg); - -/** - * Send a message to peer member of this chat room. - * @param cr #LinphoneChatRoom object - * @param msg #LinphoneChatMessage message to be sent - * @param status_cb LinphoneChatMessageStateChangeCb status callback invoked when message is delivered or could not be delivered. May be NULL - * @param ud user data for the status cb. - * @deprecated Use linphone_chat_room_send_chat_message() instead. - * @note The LinphoneChatMessage must not be destroyed until the the callback is called. - * The LinphoneChatMessage reference is transfered to the function and thus doesn't need to be unref'd by the application. - * @donotwrap - */ -LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_send_message2(LinphoneChatRoom *cr, LinphoneChatMessage* msg,LinphoneChatMessageStateChangedCb status_cb,void* ud); - -/** - * Send a message to peer member of this chat room. - * @param[in] cr LinphoneChatRoom object - * @param[in] msg LinphoneChatMessage object - * The state of the message sending will be notified via the callbacks defined in the LinphoneChatMessageCbs object that can be obtained - * by calling linphone_chat_message_get_callbacks(). - * The LinphoneChatMessage reference is transfered to the function and thus doesn't need to be unref'd by the application. - * @donotwrap - */ -LINPHONE_PUBLIC void linphone_chat_room_send_chat_message(LinphoneChatRoom *cr, LinphoneChatMessage *msg); - -/** - * Mark all messages of the conversation as read - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. - */ -LINPHONE_PUBLIC void linphone_chat_room_mark_as_read(LinphoneChatRoom *cr); - -/** - * Delete a message from the chat room history. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. - * @param[in] msg The #LinphoneChatMessage object to remove. - */ - -LINPHONE_PUBLIC void linphone_chat_room_delete_message(LinphoneChatRoom *cr, LinphoneChatMessage *msg); - -/** - * Delete all messages from the history - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. - */ -LINPHONE_PUBLIC void linphone_chat_room_delete_history(LinphoneChatRoom *cr); - -/** - * Gets the number of messages in a chat room. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which size has to be computed - * @return the number of messages. - */ -LINPHONE_PUBLIC int linphone_chat_room_get_history_size(LinphoneChatRoom *cr); - -/** - * Gets nb_message most recent messages from cr chat room, sorted from oldest to most recent. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which messages should be retrieved - * @param[in] nb_message Number of message to retrieve. 0 means everything. - * @return \bctbx_list{LinphoneChatMessage} - */ -LINPHONE_PUBLIC bctbx_list_t *linphone_chat_room_get_history(LinphoneChatRoom *cr,int nb_message); - -/** - * Gets the partial list of messages in the given range, sorted from oldest to most recent. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which messages should be retrieved - * @param[in] begin The first message of the range to be retrieved. History most recent message has index 0. - * @param[in] end The last message of the range to be retrieved. History oldest message has index of history size - 1 (use #linphone_chat_room_get_history_size to retrieve history size) - * @return \bctbx_list{LinphoneChatMessage} - */ -LINPHONE_PUBLIC bctbx_list_t *linphone_chat_room_get_history_range(LinphoneChatRoom *cr, int begin, int end); - -LINPHONE_PUBLIC LinphoneChatMessage * linphone_chat_room_find_message(LinphoneChatRoom *cr, const char *message_id); - -/** - * Notifies the destination of the chat message being composed that the user is typing a new message. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation for which a new message is being typed. - */ -LINPHONE_PUBLIC void linphone_chat_room_compose(LinphoneChatRoom *cr); - -/** - * Tells whether the remote is currently composing a message. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. - * @return TRUE if the remote is currently composing a message, FALSE otherwise. - */ -LINPHONE_PUBLIC bool_t linphone_chat_room_is_remote_composing(const LinphoneChatRoom *cr); - -/** - * Gets the number of unread messages in the chatroom. - * @param[in] cr The #LinphoneChatRoom object corresponding to the conversation. - * @return the number of unread messages. - */ -LINPHONE_PUBLIC int linphone_chat_room_get_unread_messages_count(LinphoneChatRoom *cr); - -/** - * Returns back pointer to #LinphoneCore object. - * @deprecated use linphone_chat_room_get_core() - * @donotwrap -**/ -LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneCore* linphone_chat_room_get_lc(const LinphoneChatRoom *cr); - -/** - * Returns back pointer to #LinphoneCore object. -**/ -LINPHONE_PUBLIC LinphoneCore* linphone_chat_room_get_core(const LinphoneChatRoom *cr); - -/** - * When realtime text is enabled #linphone_call_params_realtime_text_enabled, #LinphoneCoreIsComposingReceivedCb is call everytime a char is received from peer. - * At the end of remote typing a regular #LinphoneChatMessage is received with committed data from #LinphoneCoreMessageReceivedCb. - * @param[in] cr #LinphoneChatRoom object - * @returns RFC 4103/T.140 char - */ -LINPHONE_PUBLIC uint32_t linphone_chat_room_get_char(const LinphoneChatRoom *cr); - -/** - * Returns true if lime is available for given peer - * - * @return true if zrtp secrets have already been shared and ready to use - */ -LINPHONE_PUBLIC bool_t linphone_chat_room_lime_available(LinphoneChatRoom *cr); - /** * Returns an list of chat rooms * @param[in] lc #LinphoneCore object @@ -550,14 +356,6 @@ LINPHONE_PUBLIC LinphoneStatus linphone_chat_message_put_char(LinphoneChatMessag */ LINPHONE_PUBLIC const char* linphone_chat_message_get_message_id(const LinphoneChatMessage *cm); -/** - * get Curent Call associated to this chatroom if any - * To commit a message, use #linphone_chat_room_send_message - * @param[in] room LinphoneChatRomm - * @returns LinphoneCall or NULL. - */ -LINPHONE_PUBLIC LinphoneCall *linphone_chat_room_get_call(const LinphoneChatRoom *room); - /** * Get the LinphoneChatMessageCbs object associated with the LinphoneChatMessage. * @param[in] msg LinphoneChatMessage object