michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /** @mainpage VCM APIs.
michael@0:  *
michael@0:  *  @section Introduction
michael@0:  *  This module contains command APIs to the media layer
michael@0:  */
michael@0: 
michael@0: /**
michael@0:  * @file   vcm.h
michael@0:  * @brief  APIs to interface with the Media layer.
michael@0:  *
michael@0:  * This file contains API that interface to the media layer on the platform.
michael@0:  * The following APIs need to be implemented to have the sip stack interact
michael@0:  * and issue commands to the media layer.
michael@0:  */
michael@0: 
michael@0: #include "cpr_types.h"
michael@0: #include "vcm.h"
michael@0: #include "rtp_defs.h"
michael@0: #include "ccsdp.h"
michael@0: 
michael@0: 
michael@0: /**
michael@0:  *  The initialization of the VCM module
michael@0:  *
michael@0:  */
michael@0: void vcmInit()
michael@0: {
michael@0:     return ;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *   Should we remove this from external API
michael@0:  *
michael@0:  *  @param[in] mcap_id - group identifier to which stream belongs.
michael@0:  *  @param[in]     group_id         - group identifier
michael@0:  *  @param[in]     cc_stream_id        - stream identifier
michael@0:  *  @param[in]     call_handle      - call handle
michael@0:  *  @param[in]     port_requested   - requested port.
michael@0:  *  @param[in]     listen_ip        - local IP for listening
michael@0:  *  @param[in]     is_multicast     - multicast stream?
michael@0:  *  @param[in,out] port_allocated   - allocated(reserved) port
michael@0:  *
michael@0:  *  tbd need to see if we can deprecate this API
michael@0:  *
michael@0:  *  @return       0 success, ERROR failure.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: short vcmRxOpen(cc_mcapid_t mcap_id, cc_groupid_t group_id, cc_streamid_t stream_id,  cc_call_handle_t call_handle,
michael@0:                   uint16_t port_requested, cpr_ip_addr_t *listen_ip,
michael@0:                   boolean is_multicast, int *port_allocated)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: /*!
michael@0:  *  should we remove from external API
michael@0:  *
michael@0:  *  @param[in]  mcap_id - Media Capability ID
michael@0:  *  @param[in]  group_id - group to which stream belongs
michael@0:  *  @param[in]  cc_stream_id - stream identifier
michael@0:  *  @param[in]  call_handle - call handle
michael@0:  *
michael@0:  *  @return  zero(0) for success otherwise, ERROR for failure
michael@0:  *
michael@0:  */
michael@0: 
michael@0: short vcmTxOpen(cc_mcapid_t mcap_id, cc_groupid_t group_id, cc_streamid_t stream_id, cc_call_handle_t call_handle)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: 
michael@0: /*!
michael@0:  *  Allocate(Reserve) a receive port.
michael@0:  *
michael@0:  *  @param[in]  mcap_id - Media Capability ID
michael@0:  *  @param[in]  group_id - group identifier to which stream belongs.
michael@0:  *  @param[in]  cc_stream_id - stream identifier
michael@0:  *  @param[in]  call_handle  - call handle
michael@0:  *  @param[in]  port_requested - port requested (if zero -> give any)
michael@0:  *  @param[out]  port_allocated - port that was actually allocated.
michael@0:  *
michael@0:  *  @return    void
michael@0:  *
michael@0:  */
michael@0: 
michael@0: void vcmRxAllocPort(cc_mcapid_t mcap_id, cc_groupid_t group_id, cc_streamid_t stream_id,  cc_call_handle_t call_handle,
michael@0:                        uint16_t port_requested, int *port_allocated)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /*!
michael@0:  *  Release the allocated port
michael@0:  * @param[in] mcap_id   - media capability id (0 is audio)
michael@0:  * @param[in] group_id  - group identifier
michael@0:  * @param[in] cc_stream_id - stream identifier
michael@0:  * @param[in] call_handle   - call handle
michael@0:  * @param[in] port     - port to be released
michael@0:  *
michael@0:  * @return void
michael@0:  */
michael@0: 
michael@0: void vcmRxReleasePort(cc_mcapid_t mcap_id, cc_groupid_t group_id,cc_streamid_t stream_id,  cc_call_handle_t call_handle, int port)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /*!
michael@0:  *  Start receive stream
michael@0:  *  Note: For video calls, for a given call_id there will be
michael@0:  *        two media lines and the corresponding group_id/cc_stream_id pair.
michael@0:  *        One RTP session is requested from media server for each
michael@0:  *        media line(group/stream) i.e. a video call would result in
michael@0:  *        two rtp_sessions in our session info list created by two
michael@0:  *        calls to vcm_rx/tx with mcap_id of AUDIO and VIDEO respectively.
michael@0:  *
michael@0:  *  @param[in]    mcap_id     - media type id
michael@0:  *  @param[in]    group_id    - group identifier associated with the stream
michael@0:  *  @param[in]    cc_stream_id   - id of the stream one per each media line
michael@0:  *  @param[in]    call_handle     - call handle
michael@0:  *  @param[in]    payload     - payload type
michael@0:  *  @param[in]    local_addr  - local ip address to use.
michael@0:  *  @param[in]    port        - local port (receive)
michael@0:  *  @param[in]    algorithmID - crypto alogrithm ID
michael@0:  *  @param[in]    rx_key      - rx key used when algorithm ID is encrypting
michael@0:  *  @param[in]    attrs       - media attributes
michael@0:  *
michael@0:  *  @return   zero(0) for success otherwise, -1 for failure
michael@0:  *
michael@0:  */
michael@0: 
michael@0: int vcmRxStart(cc_mcapid_t mcap_id, cc_groupid_t group_id, cc_streamid_t
michael@0:                stream_id, cc_call_handle_t call_handle,
michael@0:                const vcm_payload_info_t *payload, cpr_ip_addr_t *local_addr,
michael@0:                uint16_t port, vcm_crypto_algorithmID algorithmID,
michael@0:                vcm_crypto_key_t *rx_key, vcm_mediaAttrs_t *attrs)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  start tx stream
michael@0:  *  Note: For video calls, for a given call_id there will be
michael@0:  *        two media lines and the corresponding group_id/cc_stream_id pair.
michael@0:  *        One RTP session is requested from media server for each
michael@0:  *        media line(group/stream) i.e. a video call would result in
michael@0:  *        two rtp_sessions in our session info list created by two
michael@0:  *        calls to vcm_rx/tx with mcap_id of AUDIO and VIDEO respectively.
michael@0:  *
michael@0:  *  @param[in]   mcap_id      - media cap id
michael@0:  *  @param[in]   group_id     - group identifier to which the stream belongs
michael@0:  *  @param[in]   cc_stream_id    - stream id of the given media type.
michael@0:  *  @param[in]   call_handle  - call handle
michael@0:  *  @param[in]   payload      - payload type
michael@0:  *  @param[in]   tos          - bit marking
michael@0:  *  @param[in]   local_addr   - local address
michael@0:  *  @param[in]   local_port   - local port
michael@0:  *  @param[in]   remote_ip_addr - remote ip address
michael@0:  *  @param[in]   remote_port  - remote port
michael@0:  *  @param[in]   algorithmID  - crypto alogrithm ID
michael@0:  *  @param[in]   tx_key       - tx key used when algorithm ID is encrypting.
michael@0:  *  @param[in]   attrs        - media attributes
michael@0:  *
michael@0:  *  Returns: zero(0) for success otherwise, ERROR for failure
michael@0:  *
michael@0:  */
michael@0: 
michael@0: int vcmTxStart(cc_mcapid_t mcap_id, cc_groupid_t group_id,
michael@0:                cc_streamid_t stream_id,  cc_call_handle_t call_handle,
michael@0:                const vcm_payload_info_t *payload, short tos,
michael@0:                cpr_ip_addr_t *local_addr, uint16_t local_port,
michael@0:                cpr_ip_addr_t *remote_ip_addr, uint16_t remote_port,
michael@0:                vcm_crypto_algorithmID algorithmID, vcm_crypto_key_t *tx_key,
michael@0:                vcm_mediaAttrs_t *attrs)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: 
michael@0: /*!
michael@0:  *  Close the receive stream.
michael@0:  *
michael@0:  *  @param[in]    mcap_id - Media Capability ID
michael@0:  *  @param[in]    group_id - group identifier that belongs to the stream.
michael@0:  *  @param[in]    cc_stream_id - stream id of the given media type.
michael@0:  *  @param[in]    call_handle  - call handle
michael@0:  *
michael@0:  *  @return   None
michael@0:  *
michael@0:  */
michael@0: 
michael@0: void vcmRxClose(cc_mcapid_t mcap_id, cc_groupid_t group_id,cc_streamid_t stream_id,  cc_call_handle_t call_handle)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  Close the transmit stream
michael@0:  *
michael@0:  *  @param[in] mcap_id - Media Capability ID
michael@0:  *  @param[in] group_id - identifier of the group to which stream belongs
michael@0:  *  @param[in] cc_stream_id - stream id of the given media type.
michael@0:  *  @param[in] call_handle  - call handle
michael@0:  *
michael@0:  *  @return     void
michael@0:  */
michael@0: 
michael@0: void vcmTxClose(cc_mcapid_t mcap_id, cc_groupid_t group_id, cc_streamid_t stream_id, cc_call_handle_t call_handleS)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  To be Deprecated
michael@0:  *  This may be needed to be implemented if the DSP doesn't automatically enable the side tone
michael@0:  *  The stack will make a call to this method based on the call state. Provide a stub if this is not needed.
michael@0:  *
michael@0:  *  @param[in] side_tone - boolean to enable/disable side tone
michael@0:  *
michael@0:  *  @return void
michael@0:  *
michael@0:  */
michael@0: void vcmEnableSidetone(uint16_t side_tone)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  Start a tone (continuous)
michael@0:  *
michael@0:  *  Parameters:
michael@0:  *  @param[in] tone       - tone type
michael@0:  *  @param[in] alert_info - alertinfo header
michael@0:  *  @param[in] call_handle    - call handle
michael@0:  *  @param[in] group_id - identifier of the group to which stream belongs
michael@0:  *  @param[in] cc_stream_id   - stream identifier.
michael@0:  *  @param[in] direction  - network, speaker, both
michael@0:  *
michael@0:  *  @return void
michael@0:  *
michael@0:  */
michael@0: 
michael@0: void vcmToneStart(vcm_tones_t tone, short alert_info, cc_call_handle_t call_handle, cc_groupid_t group_id,
michael@0:                     cc_streamid_t stream_id, uint16_t direction)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  * Plays a short tone. uses the open audio path.
michael@0:  * If no audio path is open, plays on speaker.
michael@0:  *
michael@0:  * @param[in] tone       - tone type
michael@0:  * @param[in] alert_info - alertinfo header
michael@0:  * @param[in] call_handle - call handle
michael@0:  * @param[in] group_id - identifier of the group to which stream belongs
michael@0:  * @param[in] cc_stream_id   - stream identifier.
michael@0:  * @param[in] direction  - network, speaker, both
michael@0:  *
michael@0:  * @return void
michael@0:  */
michael@0: 
michael@0: void vcmToneStartWithSpeakerAsBackup(vcm_tones_t tone, short alert_info, cc_call_handle_t call_handle, cc_groupid_t group_id,
michael@0:                     cc_streamid_t stream_id, uint16_t direction)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  Stop the tone being played.
michael@0:  *
michael@0:  *  Description: Stop the tone being played currently
michael@0:  *
michael@0:  *
michael@0:  * @param[in] tone - tone to be stopeed
michael@0:  * @param[in] group_id - associated stream's group
michael@0:  * @param[in] cc_stream_id - associated stream id
michael@0:  * @param[in] call_handle - the context (call) for this tone.
michael@0:  *
michael@0:  * @return void
michael@0:  *
michael@0:  */
michael@0: 
michael@0: void vcmToneStop(vcm_tones_t tone, cc_groupid_t group_id, cc_streamid_t cc_stream_id, cc_call_handle_t call_handle)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  start/stop ringing
michael@0:  *
michael@0:  *  @param[in] ringMode   - VCM ring mode (ON/OFF)
michael@0:  *  @param[in] once       - type of ring - continuous or one shot.
michael@0:  *  @param[in] alert_info - header specified ring mode.
michael@0:  *  @param[in] line       - the line on which to start/stop ringing
michael@0:  *
michael@0:  *  @return    void
michael@0:  */
michael@0: 
michael@0: void vcmControlRinger(vcm_ring_mode_t ringMode, short once,
michael@0:                         boolean alert_info, int line, cc_callid_t call_id)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Enable / disable speaker
michael@0:  *
michael@0:  * @param[in] state - true -> enable speaker, false -> disable speaker
michael@0:  *
michael@0:  * @return void
michael@0:  */
michael@0: 
michael@0: void vcmSetSpeakerMode(boolean state)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  * Get current list of audio codec that could be used
michael@0:  * @param request_type - sendonly/recvonly/sendrecv
michael@0:  */
michael@0: 
michael@0: int vcmGetAudioCodecList(int request_type)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: /**
michael@0:  * Get current list of video codec that could be used
michael@0:  * @param request_type - sendonly/recvonly/sendrecv
michael@0:  */
michael@0: 
michael@0: int vcmGetVideoCodecList(int request_type)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  * Get max supported video packetization mode for H.264 video
michael@0:  */
michael@0: /*
michael@0: int vcmGetVideoMaxSupportedPacketizationMode()
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: */
michael@0: /**
michael@0:  * Get the rx/tx stream statistics associated with the call.
michael@0:  *
michael@0:  * @param[in]  mcap_id  - media type (audio/video)
michael@0:  * @param[in]  group_id - group id of the stream
michael@0:  * @param[in]  cc_stream_id - stram id of the stream
michael@0:  * @param[in]  call_handle - call handle
michael@0:  * @param[out] rx_stats - ptr to the rx field in the stats struct
michael@0:  * @param[out] tx_stats - ptr to the tx field in the stats struct
michael@0:  *
michael@0:  */
michael@0: 
michael@0: /*
michael@0: int vcmGetRtpStats(cc_mcapid_t mcap_id, cc_groupid_t group_id,
michael@0:                       cc_streamid_t stream_id, cc_call_handle_t call_handle,
michael@0:                       char *rx_stats, char *tx_stats)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: */
michael@0: 
michael@0: /**
michael@0:  *
michael@0:  * The wlan interface puts into unique situation where call control
michael@0:  * has to allocate the worst case bandwith before creating a
michael@0:  * inbound or outbound call. The function call will interface through
michael@0:  * media API into wlan to get the call bandwidth. The function
michael@0:  * return is asynchronous and will block till the return media
michael@0:  * callback signals to continue the execution.
michael@0:  *
michael@0:  * @note If not using WLAN interface simply return true
michael@0:  *
michael@0:  * @return true if the bandwidth can be allocated else false.
michael@0:  */
michael@0: 
michael@0: /*
michael@0: boolean vcmAllocateBandwidth(cc_call_handle_t call_handle, int sessions)
michael@0: {
michael@0:     return TRUE;
michael@0: }
michael@0: */
michael@0: 
michael@0: /**
michael@0:  *
michael@0:  * Free the bandwidth allocated for this call
michael@0:  * using the vcmAllocateBandwidth API
michael@0:  *
michael@0:  * @note  If not using WLAN provide a stub
michael@0:  */
michael@0: 
michael@0: /*
michael@0: void vcmRemoveBandwidth(cc_call_handle_t call_handle)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: */
michael@0: 
michael@0: /**
michael@0:  * @brief vcmActivateWlan
michael@0:  *
michael@0:  * Free the bandwidth allocated for this call
michael@0:  * using the vcmAllocateBandwidth API
michael@0:  *
michael@0:  * @note If not using WLAN provide a stub
michael@0:  */
michael@0: 
michael@0: /*
michael@0: void vcmActivateWlan(boolean is_active)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: */
michael@0: 
michael@0: /**
michael@0:  *  free the media pointer allocated in vcm_negotiate_attrs method
michael@0:  *
michael@0:  *  @param ptr - pointer to be freed
michael@0:  *
michael@0:  *  @return  void
michael@0:  */
michael@0: void vcmFreeMediaPtr(void *ptr)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  *  MEDIA control received from far end on signaling path
michael@0:  *
michael@0:  *  @param call_handle - call handle of the call
michael@0:  *  @param to_encoder - the control request received
michael@0:  *        Only FAST_PICTURE_UPDATE is supported
michael@0:  *
michael@0:  *  @return  void
michael@0:  *
michael@0:  */
michael@0: 
michael@0: /*
michael@0: void vcmMediaControl(cc_call_handle_t call_handle, vcm_media_control_to_encoder_t to_encoder)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: */
michael@0: 
michael@0: /**
michael@0:  *  specifies DSCP marking for RTCP streams
michael@0:  *
michael@0:  *  @param group_id - call_id of the call
michael@0:  *  @param dscp - the DSCP value to be used
michael@0:  *
michael@0:  *  @return  void
michael@0:  */
michael@0: 
michael@0: /*
michael@0: void vcmSetRtcpDscp(cc_groupid_t group_id, int dscp)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: */
michael@0: 
michael@0: /**
michael@0:  * Verify if the SDP attributes for the requested video codec are acceptable
michael@0:  *
michael@0:  * This method is called for video codecs only. This method should parse the
michael@0:  * Video SDP attributes using the SDP helper API and verify if received
michael@0:  * attributes are acceptable. If the attributes are acceptable any attribute
michael@0:  * values if needed by vcmTxStart method should be bundled in the desired
michael@0:  * structure and its pointer should be returned in rccappptr. This opaque
michael@0:  * pointer shall be provided again when vcmTxStart is invoked.
michael@0:  *
michael@0:  * @param [in] media_type - codec for which we are negotiating
michael@0:  * @param [in] sdp_p - opaque SDP pointer to be used via SDP helper APIs
michael@0:  * @param [in] level - Parameter to be used with SDP helper APIs
michael@0:  * @param [out] rcapptr - variable to return the allocated attrib structure
michael@0:  *
michael@0:  * @return boolean - true if attributes are accepted false otherwise
michael@0:  */
michael@0: 
michael@0: boolean vcmCheckAttribs(uint32_t media_type, void *sdp_p, int level, void **rcapptr)
michael@0: {
michael@0:     return TRUE;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  * Add Video attributes in the offer/answer SDP
michael@0:  *
michael@0:  * This method is called for video codecs only. This method should populate the
michael@0:  * Video SDP attributes using the SDP helper API
michael@0:  *
michael@0:  * @param [in] sdp_p - opaque SDP pointer to be used via SDP helper APIs
michael@0:  * @param [in] level - Parameter to be used with SDP helper APIs
michael@0:  * @param [in] media_type - codec for which the SDP attributes are to be populated
michael@0:  * @param [in] payload_number - RTP payload type used for the SDP
michael@0:  * @param [in] isOffer - boolean indicating we are encoding an offer or an aswer
michael@0:  *
michael@0:  * @return void
michael@0:  */
michael@0: 
michael@0: 
michael@0: void vcmPopulateAttribs(void *sdp_p, int level, uint32_t media_type,
michael@0:                           uint16_t payload_number, boolean isOffer)
michael@0: {
michael@0:     return;
michael@0: }
michael@0: 
michael@0: /**
michael@0:  * Send a DTMF digit
michael@0:  *
michael@0:  * This method is called for sending a DTMF tone for the specified duration
michael@0:  *
michael@0:  * @param [in] digit - the DTMF digit that needs to be played out.
michael@0:  * @param [in] duration - duration of the tone
michael@0:  * @param [in] direction - direction in which the tone needs to be played.
michael@0:  *
michael@0:  * @return void
michael@0:  */
michael@0: 
michael@0: /*
michael@0: int vcmDtmfBurst(int digit, int duration, int direction)
michael@0: {
michael@0:     return 0;
michael@0: }
michael@0: */
michael@0: 
michael@0: /*
michael@0: int vcmGetILBCMode()
michael@0: {
michael@0:     return SIPSDP_ILBC_MODE20;
michael@0: }
michael@0: */