陈明泉 / vipTalk

/************************************************************************

        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__ */