陈明泉 / 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_call.h
  Module        : multimedia talk client
  Author        : leo.lv
  Created on    : 2011-01-03
  Description   :
      Data structure and function declare required by MTC call

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

/**
 * @file mtc_call_ext.h
 * @brief MTC Call Interface Functions
 *
 * This file includes call interface function. Those function is used to manage calls.
 */
#ifdef __cplusplus
extern "C" {
#endif

/** @brief MTC call record file type */
#define MTC_CALL_REC_FILE_PCM "pcm"  /**< @brief Pcm content. */
#define MTC_CALL_REC_FILE_WAV "wav"  /**< @brief Wav content. */

/** @brief MTC call alert information type */
typedef enum EN_MTC_CALL_ALERT_INFO_TYPE
{
    EN_MTC_CALL_ALERT_INFO_NULL,     /**< @brief No alert info. */   
    EN_MTC_CALL_ALERT_INFO_DR0,      /**< @brief Bellcore_dr0. */
    EN_MTC_CALL_ALERT_INFO_DR1,      /**< @brief Bellcore_dr1. */
    EN_MTC_CALL_ALERT_INFO_DR2,      /**< @brief Bellcore_dr2. */
    EN_MTC_CALL_ALERT_INFO_DR3,      /**< @brief Bellcore_dr3. */
    EN_MTC_CALL_ALERT_INFO_DR4,      /**< @brief Bellcore_dr4. */
    EN_MTC_CALL_ALERT_INFO_DR5       /**< @brief Bellcore_dr5. */
} EN_MTC_CALL_ALERT_INFO_TYPE;

/** @brief MTC call ealry media direction */
typedef enum EN_MTC_CALL_EM_STATUS_TYPE
{
    EN_MTC_CALL_EM_STATUS_INACTIVE,  /**< @brief Inactive. */
    EN_MTC_CALL_EM_STATUS_SENDONLY,  /**< @brief Sendonly. */
    EN_MTC_CALL_EM_STATUS_RECVONLY,  /**< @brief Recvonly. */
    EN_MTC_CALL_EM_STATUS_SENDRECV,  /**< @brief Sendrecv. */
} EN_MTC_CALL_EM_STATUS_TYPE;

/** 
 * @brief MTC session get video size.
 *
 * @param [in] iCallId The ID of session.
 * @param [out] piWidth Video width in pixel of specific session.
 * @param [out] piHeight Video height in pixel of specific session.
 *
 * @retval ZOK on succeed.
 * @retval ZFAILED on failure.
 */
MTCFUNC ZINT Mtc_CallGetVideoSize(ZUINT iCallId, ZUINT *piWidth,
                ZUINT *piHeight);

/** 
 * @brief MTC session get remote video size.
 *
 * @param [in] iCallId The ID of session.
 * @param [out] piWidth Video width in pixel of specific session.
 * @param [out] piHeight Video height in pixel of specific session.
 *
 * @retval ZOK on succeed.
 * @retval ZFAILED on failure.
 */
MTCFUNC ZINT Mtc_CallGetVideoRemoteSize(ZUINT iCallId, ZUINT *piWidth,
                ZUINT *piHeight);

/** 
 * @brief MTC session get local video size.
 *
 * @param [in] iCallId The ID of session.
 * @param [out] piWidth Video width in pixel of specific session.
 * @param [out] piHeight Video height in pixel of specific session.
 *
 * @retval ZOK on succeed.
 * @retval ZFAILED on failure.
 */
MTCFUNC ZINT Mtc_CallGetVideoLocalSize(ZUINT iCallId, ZUINT *piWidth,
                ZUINT *piHeight);

/** 
 * @brief MTC session get Call-ID string.
 *
 * @param [in] iCallId The ID of session which you want to get.
 *
 * @return The string of Call-ID.
 *
 * @see
 */
MTCFUNC ZCONST ZCHAR * Mtc_CallGetSipCallId(ZUINT iCallId);

/** 
 * @brief MTC session get peer id, based on polices.
 *
 * @param [in] iCallId The ID of session which you want to get.
 * @param [out] ppcDispName The display name of peer user which you have this session with.
 * @param [out] ppcUri The URI of peer user which you have this session with.
 *
 * @retval ZOK on succeed.
 * @retval ZFAILED on failure.
 *
 * Note the result of this function may be different with Mtc_CallGetPeerUri
 * because the apply of polices. For example, OIP, OIR, TIP, TIR, and privacy.
 *
 * @see @ref Mtc_CallGetPeerUri
 */
MTCFUNC ZINT Mtc_CallGetPeerId(ZUINT iCallId, ZCHAR **ppcDispName, 
                ZCHAR **ppcUri);

/** 
 * @brief MTC session check if the peer is contains isfocus parameter.
 *
 * @param [in] iCallId The ID of session.
 *
 * @retval ZTRUE on peer is focus.
 * @retval ZFALSE on peer no focus.
 */
MTCFUNC ZBOOL Mtc_CallPeerIsFocus(ZUINT iCallId);

/** 
 * @brief MTC session check if the offer/answer exchange is completed.
 *
 * @param [in] iCallId The ID of session.
 *
 * @retval ZTRUE on offer has answer.
 * @retval ZFALSE on offer has not answer.
 *
 * @see @ref Mtc_CallGetEarlyMediaStatus
 */
MTCFUNC ZBOOL Mtc_CallHasOfferAnswer(ZUINT iCallId);

/** 
 * @brief MTC session get alert information type.
 *
 * @param [in] iCallId The ID of session which you want to get.
 *
 * @retval @ref EN_MTC_CALL_ALERT_INFO_TYPE.
 *
 * The information get by this function is actually from Alert-Info header 
 * in SIP message.
 */
MTCFUNC ZUINT Mtc_CallGetAlertInfo(ZUINT iCallId);

/** 
 * @brief MTC session get the early media status.
 *
 * @param [in] iCallId The ID of session which you want to get its early media
 *                      status.
 * @param [in] bVideo If ZTRUE, get video status, otherwise get audio status.
 *
 * @retval @ref EN_MTC_CALL_EM_STATUS_TYPE.
 *
 * @see @ref Mtc_CallHasOfferAnswer
 */
MTCFUNC ZUINT Mtc_CallGetEarlyMediaStatus(ZUINT iCallId, 
                ZBOOL bVideo);

/**
 * @brief Reccord mic start.
 *
 * It will reccord from mic to file.
 *
 * @param [in] pcFileName The reccord file name.
 * @param [in] ucFileType The reccord file type, @ref EN_MTC_MFILE_TYPE
 *
 * @retval ZOK Audio Reccord  successfully.
 * @retval ZFAILED Audio Reccord failed.
 *
 * @see @ref Mtc_CallRecMicStop
 */
MTCFUNC ZINT Mtc_CallRecMicStart(ZCONST ZCHAR *pcFileName, 
                ZUCHAR ucFileType);

/**
 * @brief Reccord Audio stop.
 *
 * @see @ref Mtc_CallRecMicStart
 */
MTCFUNC ZINT Mtc_CallRecMicStop(ZFUNC_VOID);

/** 
 * @brief MTC session record playout.
 *
 * @param [in] iCallId The ID of session which you want to record, 
 *                      if pCall is invalid, record the mix playout.
 * @param [in] pcFileName The reccord file name.
 * @param [in] ucFileType The reccord file type, @ref EN_MTC_MFILE_TYPE
 *
 * @retval ZOK on succeed.
 * @retval ZFAILED on failure.
 */
MTCFUNC ZINT Mtc_CallRecPlayStart(ZUINT iCallId, ZCONST ZCHAR *pcFileName, 
                ZUCHAR ucFileType);

/** 
 * @brief MTC session stop record playout.
 *
 * @param [in] iCallId The ID of session which you want to stop record, 
 *                      if pCall is invalid, stop record the mix playout.
 *
 * @retval ZOK on succeed.
 * @retval ZFAILED on failure.
 */
MTCFUNC ZINT Mtc_CallRecPlayStop(ZUINT iCallId);

/**
 * @brief Query missed call information.
 *
 * @retval ZOK Query OK.
 * @retval ZFAILED Query failed.
 */
MTCFUNC ZINT Mtc_CallQueryMissed(ZFUNC_VOID);

#define MTC_CALL_CONNECTION_STATE_INVALID    "INVALID"
#define MTC_CALL_CONNECTION_STATE_IDLE       "IDLE"
#define MTC_CALL_CONNECTION_STATE_CONNECTING "CONNECTING"
#define MTC_CALL_CONNECTION_STATE_CONNECTED  "CONNECTED"

/**
 * @brief Get media connection state of call.
 *
 * @return Connection state information string,
 * MTC_CALL_CONNECTION_STATE_INVALID for invalid call.
 */
MTCFUNC ZCONST ZCHAR * Mtc_CallMediaState(ZUINT iCallId);

#ifdef __cplusplus
}
#endif

#endif /* _MTC_CALL_EXT_H__ */