陈明泉 / 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_buddy.h
  Module        : multimedia talk client
  Author        : xiangbo.hui
  Created on    : 2015-03-27
  Description   :
      Data structure and function declare required by MTC statistics

  Modify History:
  1. Date:        Author:         Modification:
*************************************************/
#ifndef _MTC_BUDDY_H__
#define _MTC_BUDDY_H__

/**
 * @file mtc_buddy.h
 * @brief MTC Buddy Interface Functions
 *
 * This file includes buddy interface function.
 */

/**
 * @defgroup MtcBuddyKey MTC notification key for buddy.
 * @{
 */

/**
 * @brief A key whose value is a string object reflecting
 * the buddy's URI.
 */
#define MtcBuddyUriKey              "MtcBuddyUriKey"

/**
 * @brief A key whose value is a string object reflecting
 * the buddy's reason key.
 */
#define MtcBuddyReasonKey           "MtcBuddyReasonKey"

/**
 * @brief A key whose value is a string object reflecting
 * the property's name
 */
#define MtcBuddyPropertyNameKey     "MtcBuddyPropertyNameKey"

/**
 * @brief A key whose value is a string object reflecting
 * the property's value
 */
#define MtcBuddyPropertyValueKey    "MtcBuddyPropertyValueKey"

/**
 * @brief A key whose value is a number reflecting the account's status,
 * @ref group_def_account_status.
 */
#define MtcBuddyStatusKey           "Status"

/**
 * @brief A key whose value is a number object reflecting
 * the login date time by UNIX timestamp.
 */
#define MtcBuddyPropertyDateKey     "Date"

/**
 * @brief A key whose value is a string object reflecting
 * the brand of device.
 */
#define MtcBuddyPropertyBrandKey    "Brand"

/**
 * @brief A key whose value is a string object reflecting
 * the model of device.
 */
#define MtcBuddyPropertyModelKey    "Model"

/**
 * @brief A key whose value is a string object reflecting
 * the OS version of device.
 */
#define MtcBuddyPropertyVersionKey  "Ver"

/**
 * @brief A key whose value is a string object reflecting
 * the application version.
 */
#define MtcBuddyPropertyAppVersionKey   "AppVer"

/** @} */

/**
 * @defgroup MtcBuddyNotification MTC notification names for buddy.
 * @{
 */

/**
 * @brief Posted when query buddy property successfully.
 *
 * The pcInfo of this notification contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyPropertyNameKey and @ref MtcBuddyPropertyValueKey.
 */
#define MtcBuddyQueryPropertyOkNotification "MtcBuddyQueryPropertyOkNotification"

/**
 * @brief Posted when query buddy property failed.
 *
 * The pcInfo of this notification is contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyReasonKey.
 */
#define MtcBuddyQueryPropertyDidFailNotification "MtcBuddyQueryPropertyDidFailNotification"

/**
 * @brief Posted when query buddy login information successfully.
 *
 * The pcInfo of this notification contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyStatusKey, @ref MtcBuddyPropertyDateKey,
 * @ref MtcBuddyPropertyBrandKey, @ref MtcBuddyPropertyModelKey,
 * @ref MtcBuddyPropertyVersionKey, @ref MtcBuddyPropertyAppVersionKey.
 */
#define MtcBuddyQueryLoginPropertiesOkNotification "MtcBuddyQueryLoginPropertiesOkNotification"

/**
 * @brief Posted when query buddy login information failed.
 *
 * The pcInfo of this notification is contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyReasonKey.
 */
#define MtcBuddyQueryLoginPropertiesDidFailNotification "MtcBuddyQueryLoginPropertiesDidFailNotification"

/**
 * @brief Posted when query buddy login information successfully.
 *
 * The pcInfo of this notification contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyStatusKey.
 */
#define MtcBuddyQueryLoginInfoOkNotification "MtcBuddyQueryLoginInfoOkNotification"

/**
 * @brief Posted when query buddy login information failed.
 *
 * The pcInfo of this notification is contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyReasonKey.
 */
#define MtcBuddyQueryLoginInfoDidFailNotification "MtcBuddyQueryLoginInfoDidFailNotification"

/**
 * @brief Posted when query buddys' UserId successfully.
 *
 * The pcInfo of this notification contains an array of UserId map item.
 * Each item is an array of string, the first string is User's URI,
 * the second string is corresponding UserId.
 */
#define MtcBuddyQueryUserIdOkNotification "MtcBuddyQueryUserIdOkNotification"

/**
 * @brief Posted when query buddys' UserId failed.
 *
 * The pcInfo is ZNULL.
 */
#define MtcBuddyQueryUserIdDidFailNotification "MtcBuddyQueryUserIdDidFailNotification"

/**
 * @brief Posted when query users' status successfully.
 *
 * The pcInfo of this notification is an array, each item contains
 * @ref MtcBuddyUriKey, @ref MtcBuddyStatusKey.
 */
#define MtcBuddyQueryUsersStatusOkNotification "MtcBuddyQueryUsersStatusOkNotification"

/**
 * @brief Posted when query users' status failed.
 *
 * The pcInfo is ZNULL.
 */
#define MtcBuddyQueryUsersStatusDidFailNotification "MtcBuddyQueryUsersStatusDidFailNotification"

/** @} */

/**
 * @defgroup MtcBuddyReason MTC reason string.
 * @{
 */

#define MTC_ERROR_BUDDY_NOT_FOUND       "MtcBuddy.NotFound"
#define MTC_ERROR_BUDDY_NO_PROPERTY     "MtcBuddy.NoProperty"
#define MTC_ERROR_BUDDY_TIMEOUT         "MtcBuddy.Timeout"

/** @} */


#ifdef __cplusplus
extern "C" {
#endif

/** 
 * @brief Query buddy's property.
 *
 * @param [in] zCookie The cookie which you want to set.
 * @param [in] pcUri The query user's URI.
 * @param [in] pcName The query property's name.
 *
 * @retval ZOK on invoke this interface successfully. The result will notify
 * to user with @ref MtcBuddyQueryPropertyOkNotification 
 * or @ref MtcBuddyQueryPropertyDidFailNotification.
 * @retval ZFAILED failed
 */
MTCFUNC ZINT Mtc_BuddyQueryProperty(ZCOOKIE zCookie,
    ZCONST ZCHAR *pcUri, ZCONST ZCHAR *pcName);

/** 
 * @brief Query buddy's login information.
 *
 * @param [in] zCookie The cookie which you want to set.
 * @param [in] pcUri The query user's URI.
 *
 * @retval ZOK on invoke this interface successfully. The result will notify
 * to user with @ref MtcBuddyQueryLoginPropertiesOkNotification 
 * or @ref MtcBuddyQueryLoginPropertiesDidFailNotification.
 * @retval ZFAILED failed
 */
MTCFUNC ZINT Mtc_BuddyQueryLoginProperties(ZCOOKIE zCookie,
    ZCONST ZCHAR *pcUri);

/** 
 * @brief Query buddy's login information.
 *
 * @param [in] zCookie The cookie which you want to set.
 * @param [in] pcUri The query user's URI.
 * @param [in] iExpireSeconds The expiration seconds for query.
 *
 * @retval ZOK on invoke this interface successfully. The result will notify
 * to user with @ref MtcBuddyQueryLoginInfoOkNotification 
 * or @ref MtcBuddyQueryLoginInfoDidFailNotification.
 * @retval ZFAILED failed
 */
MTCFUNC ZINT Mtc_BuddyQueryLoginInfo(ZCOOKIE zCookie,
    ZCONST ZCHAR *pcUri, ZINT iExpireSeconds);

/**
 * @brief Query buddy's UserId information.
 * 
 * @param  zCookie The cookie value.
 * @param  pcInfo  The query information. For just one user, using its URI directily.
 *                 For multiple users, it must be a string in JSON format,
 *                 which contains an array of string. Each string is the user's URI
 *                 which wants be queried.
 *                 
 * @retval ZOK on invoke this interface successfully. The result will notify
 * to user with @ref MtcBuddyQueryUserIdOkNotification 
 * or @ref MtcBuddyQueryUserIdDidFailNotification.
 * @retval ZFAILED failed
 */
MTCFUNC ZINT Mtc_BuddyQueryUserId(ZCOOKIE zCookie, ZCONST ZCHAR *pcInfo);

/**
 * @brief Query users' login status.
 * 
 * @param  zCookie The cookie value
 * @param  pcInfo  The string of a JSON array, each item is the string of user's URI.
 * 
 * @retval ZOK on invoke this interface successfully. The result will notify
 * to user with @ref MtcBuddyQueryUsersStatusOkNotification
 * or @ref MtcBuddyQueryUsersStatusDidFailNotification.
 * @retval ZFAILED failed
 */
MTCFUNC ZINT Mtc_BuddyQueryUsersStatus(ZCOOKIE zCookie, ZCONST ZCHAR *pcInfo);

#ifdef __cplusplus
}
#endif

#endif /* _MTC_BUDDY_H__ */