/************************************************************************ Copyright (c) 2005-2011 by Juphoon System Software, Inc. All rights reserved. This software is confidential and proprietary to Juphoon System, Inc. No part of this software may be reproduced, stored, transmitted, disclosed or used in any form or by any means other than as expressly provided by the written license agreement between Juphoon and its licensee. THIS SOFTWARE IS PROVIDED BY JUPHOON "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JUPHOON BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Juphoon System Software, Inc. Email: support@juphoon.com Web: http://www.juphoon.com ************************************************************************/ /************************************************* File name : mtc_im.h Module : rich session enabler Author : bob.liu Created on : 2015-06-17 Description : Data structure and function declare required by mtc conference Modify History: 1. Date: Author: Modification: *************************************************/ #ifndef _MTC_IM_H__ #define _MTC_IM_H__ /** * @file * @brief MTC Instant Message Interfaces * * This file includes instant message interface function. */ #ifdef __cplusplus extern "C" { #endif /** * @defgroup MtcImKey MTC notification key of conference event. * @{ */ /** * @brief A key whose value is a number object in json format reflecting * ID of IM message. */ #define MtcImMsgIdKey "MtcImMsgIdKey" /** * @brief A key whose value is a string object in json format reflecting * the user's URI. */ #define MtcImUserUriKey "MtcImUserUriKey" /** * @brief A key whose value is a number object in json format reflecting * progress of sending in percentage. */ #define MtcImProgressKey "MtcImProgressKey" /** * @brief A key whose value is a number object in json format reflecting * the seconds from 00:00:00 Jun. 1st, 1970. */ #define MtcImTimeKey "MtcImTimeKey" /** * @brief A key whose value is a number object in json format reflecting * the content text of message. */ #define MtcImTextKey "MtcImTextKey" /** * @brief A key whose value is a number object in json format reflecting * the digest of text message. */ #define MtcImDigestKey "MtcImDigestKey" /** * @brief A key whose value is a string object reflecting the information * content. */ #define MtcImInfoContentKey "MtcImInfoContentKey" /** * @brief A key whose value is a string object reflecting the information * type. */ #define MtcImInfoTypeKey "MtcImInfoTypeKey" /** * @brief A key whose value is a number object in json format reflecting * the information type @ref EN_MTC_IM_FILE_TYPE. */ #define MtcImFileTypeKey "MtcImFileTypeKey" /** * @brief A key whose value is a string object in json format reflecting * the name of the file. */ #define MtcImFileNameKey "MtcImFileNameKey" /** * @brief A key whose value is a string object in json format reflecting * the path of the file. */ #define MtcImFilePathKey "MtcImFilePathKey" /** * @brief A key whose value is a string object in json format reflecting * the name of thumbnail file. */ #define MtcImThumbFilePathKey "MtcImThumbFilePathKey" /** * @brief A key whose value is a string object in json format reflecting * the name of the file. */ #define MtcImFileUriKey "MtcImFileUriKey" /** * @brief A key whose value is a string object in json format reflecting * the name of thumbnail file. */ #define MtcImThumbFileUriKey "MtcImThumbFileUriKey" /** * @brief A key whose value is a sting object in json format reflecting * the title of the message. */ #define MtcImTitleKey "MtcImTitleKey" /** * @brief A key whose value is a string object in json format reflecting * the display name. */ #define MtcImDisplayNameKey "MtcImDisplayNameKey" /** * @brief A key whose value is a string object in json format reflecting * the user data. */ #define MtcImUserDataKey "MtcImUserDataKey" /** * @brief A key whose value is a string object in json format reflecting * the fail description. */ #define MtcImFailDescriptionKey "MtcImFailDescriptionKey" /** @} */ /** * @defgroup MtcImNotification MTC notification of conference event. * @{ */ /** * @brief Posted when message sending. * * The pcInfo of this notification contains @ref MtcImProgressKey. */ #define MtcImSendingNotification "MtcImSendingNotification" /** * @brief Posted when message send OK. * * The pcInfo of this notification contains @ref MtcImMsgIdKey. */ #define MtcImSendOkNotification "MtcImSendOkNotification" /** * @brief Posted when message send fail. * * The pcInfo is ZNULL. */ #define MtcImSendDidFailNotification "MtcImSendDidFailNotification" /** * @brief Posted when file is fetching. * * The pcInfo of this notification contains @ref MtcImProgressKey. */ #define MtcImFetchingNotification "MtcImFetchingNotification" /** * @brief Posted when fetch file OK. * * The pcInfo of this notification contains @ref MtcImFileUriKey, * @ref MtcImFilePathKey. */ #define MtcImFetchOkNotification "MtcImFetchOkNotification" /** * @brief Posted when fetch file fail. * * The pcInfo of this notification contains @ref MtcImFileUriKey, * @ref MtcImFilePathKey. */ #define MtcImFetchDidFailNotification "MtcImFetchDidFailNotification" /** * @brief Posted when a text message received. * * The pcInfo of this notification contains @ref MtcImUserUriKey, * @ref MtcImMsgIdKey, @ref MtcImTimeKey, @ref MtcImTextKey. */ #define MtcImTextDidReceiveNotification "MtcImTextDidReceiveNotification" /** * @brief Posted when a infomation message received. * * The pcInfo of this notification contains @ref MtcImMsgIdKey, * @ref MtcImUserUriKey, @ref MtcImTimeKey, @ref MtcImInfoTypeKey, * @ref MtcImInfoContentKey */ #define MtcImInfoDidReceiveNotification "MtcImInfoDidReceiveNotification" /** * @brief Posted when a file message received. * * The pcInfo of this notification contains @ref MtcImMsgIdKey, * @ref MtcImUserUriKey, @ref MtcImTimeKey, @ref MtcImFileTypeKey and * other information which depends on the type. * * The user should fetch the file from server by @ref Mtc_ImFetchFile. */ #define MtcImFileDidReceiveNotification "MtcImFileDidReceiveNotification" /** * @brief Posted when message has been delivered to peer. * * The pcInfo of this notification contains @ref MtcImUserUriKey, * @ref MtcImMsgIdKey. */ #define MtcImDeliveredNotification "MtcImDeliveredNotification" /** * @brief Posted when message has been displayed on peer user's device. * * The pcInfo of this notification contains @ref MtcImUserUriKey, * @ref MtcImMsgIdKey. */ #define MtcImDisplayedNotification "MtcImDisplayedNotification" /** @} */ /** * @brief Send text message to peer. * * The sending progress will be notified by @ref MtcImSendingNotification. * When the message has been sent successfully, @ref MtcImSendOkNotification will * be reported. * When the mssage sent fail, @ref MtcImSendDidFailNotification will be reported. * * The peer user will be notified by @ref MtcImTextDidReceiveNotification. * * @param zCookie The user defined cookie. * @param pcUserUri The target user's URI. * @param pcText The content text of the message. * @param pcInfo The more info in JSON format, which may contain * @ref MtcImDisplayNameKey, @ref MtcImUserDataKey. * * @retval ZOK The request has been sent successfully. * @retval ZFAILED Failed to send the request. */ MTCFUNC ZINT Mtc_ImSendText(ZCOOKIE zCookie, ZCONST ZCHAR *pcUserUri, ZCONST ZCHAR *pcText, ZCONST ZCHAR *pcInfo); /** * @brief Send information to peer. * * The sending progress will be notified by @ref MtcImSendingNotification. * When the message has been sent successfully, @ref MtcImSendOkNotification will * be reported. * When the mssage sent fail, @ref MtcImSendDidFailNotification will be reported. * * The peer user will be notified by @ref MtcImInfoDidReceiveNotification. * * @param zCookie The user defined cookie. * @param pcUserUri The target user's URI. * @param pcInfoType The information type string. * @param pcContent The information content. * @param pcInfo The more info in JSON format, which may contain * @ref MtcImDisplayNameKey, @ref MtcImUserDataKey. * * @retval ZOK The request has been sent successfully. * @retval ZFAILED Failed to send the request. */ MTCFUNC ZINT Mtc_ImSendInfo(ZCOOKIE zCookie, ZCONST ZCHAR *pcUserUri, ZCONST ZCHAR *pcInfoType, ZCONST ZCHAR *pcContent, ZCONST ZCHAR *pcInfo); /** * @brief File type. */ typedef enum EN_MTC_IM_FILE_TYPE { EN_MTC_IM_FILE_TYPE_MIN = 40, /** * @brief The file is a regular file. * * The pcInfo of @ref Mtc_ImSendFile may contain * @ref MtcImDisplayNameKey,@ref MtcImUserDataKey. * * The pcInfo of notification contains @ref MtcImUserDataKey, * @ref MtcImFileNameKey, @ref MtcImFileUriKey. */ EN_MTC_IM_FILE_REGULAR, /** * @brief The file is a image file. * * The pcInfo of @ref Mtc_ImSendFile may contain * @ref MtcImDisplayNameKey,@ref MtcImUserDataKey, * @ref MtcImThumbFilePathKey, * * The pcInfo of notification contains @ref MtcImUserDataKey, * @ref MtcImFileNameKey, @ref MtcImFileUriKey, @ref MtcImThumbFileUriKey. */ EN_MTC_IM_FILE_IMAGE, /** * @brief The file is a voice file. * * The pcInfo of @ref Mtc_ImSendFile may contain * @ref MtcImDisplayNameKey,@ref MtcImUserDataKey. * * The pcInfo of notification contains @ref MtcImUserDataKey, * @ref MtcImFileNameKey, @ref MtcImFileUriKey. */ EN_MTC_IM_FILE_VOICE, /** * @brief The file is a video file. * * The pcInfo of @ref Mtc_ImSendFile may contain * @ref MtcImDisplayNameKey,@ref MtcImUserDataKey, * @ref MtcImThumbFilePathKey, @ref MtcImTitleKey. * * The pcInfo of notification contains @ref MtcImUserDataKey, * @ref MtcImTitleKey, @ref MtcImFileNameKey, @ref MtcImFileUriKey, * @ref MtcImThumbFileUriKey. */ EN_MTC_IM_FILE_VIDEO, EN_MTC_IM_FILE_TYPE_MAX } EN_MTC_IM_FILE_TYPE; /** * @brief Send file to peer. * * The sending progress will be notified by @ref MtcImSendingNotification. * When the message has been sent successfully, @ref MtcImSendOkNotification will * be reported. * When the mssage sent fail, @ref MtcImSendDidFailNotification will be reported. * * The peer user will be notified by @ref MtcImFileDidReceiveNotification. * * @param zCookie The user defined cookie. * @param pcUserUri The target user's URI. * @param iFileType The file type, @ref EN_MTC_IM_FILE_TYPE. * @param pcFilePath The name of the file. * @param pcInfo The file's information in JSON format string. * * @retval ZOK The request has been sent successfully. * @retval ZFAILED Failed to send the request. */ MTCFUNC ZINT Mtc_ImSendFile(ZCOOKIE zCookie, ZCONST ZCHAR *pcUserUri, ZINT iFileType, ZCONST ZCHAR *pcFilePath, ZCONST ZCHAR *pcInfo); /** * @brief Fetch file from server. * * The sending progress will be notified by @ref MtcImFetchingNotification. * When the message has been sent successfully, @ref MtcImFetchOkNotification will * be reported. * When the mssage sent fail, @ref MtcImFetchDidFailNotification will be reported. * * @param zCookie The user defined cookie. * @param pcFileUri The file URI. * @param pcFilePath The local file name to save file content. * * @retval ZOK The request has been sent successfully. * @retval ZFAILED Failed to send the request. */ MTCFUNC ZINT Mtc_ImFetchFile(ZCOOKIE zCookie, ZCONST ZCHAR *pcFileUri, ZCONST ZCHAR *pcFilePath); /** * @brief Notify the sender the message has been delivered to the target user. * * @param pcUserUri The target user's URI. * @param qwMsgId The message ID. * * @retval ZOK The notification has been sent successfully. * @retval ZFAILED Failed to send the notification. */ MTCFUNC ZINT Mtc_ImDidDeliver(ZCONST ZCHAR *pcUserUri, ZINT64 qwMsgId); /** * @brief Notify the sender the message has been displayed on the target user's device. * * @param pcUserUri The target user's URI. * @param qwMsgId The message ID. * * @retval ZOK The notification has been sent successfully. * @retval ZFAILED Failed to send the notification. */ MTCFUNC ZINT Mtc_ImDidDisplay(ZCONST ZCHAR *pcUserUri, ZINT64 qwMsgId); /** * @brief Refresh unreceived messages. * * @retval ZOK The refresh request has been sent successfully. * Un-received message will be notified by @ref MtcImTextDidReceiveNotification * @ref MtcImInfoDidReceiveNotification or @ref MtcImFileDidReceiveNotification * @retval ZFAILED Failed to refresh messages. */ MTCFUNC ZINT Mtc_ImRefresh(); #ifdef __cplusplus } #endif #endif /* _MTC_IM_H__ */