amsip session interface

Functions
int	am_session_start_media (const char *identity, const char *url, const char *proxy, const char *route, enum am_media_type *media_types)
int	am_session_start (const char *identity, const char *url, const char *proxy, const char *route)
int	am_session_start_with_video (const char *identity, const char *url, const char *proxy, const char *route)
int	am_session_start_screensharing (const char *identity, const char *url, const char *proxy, const char *route)
int	am_session_start_dataevents (const char *identity, const char *url, const char *proxy, const char *route)
int	am_session_answer (int tid, int did, int code, int enable_audio)
int	am_session_conference_answer (int conf_id, int tid, int did, int code, int enable_audio)
int	am_session_answer_with_video (int tid, int did, int code, int enable_audio, int enable_video)
int	am_session_conference_answer_with_video (int conf_id, int tid, int did, int code, int enable_audio, int enable_video)
int	am_session_redirect (int tid, int did, int code, const char *url)
int	am_session_stop (int cid, int did, int code)
int	am_session_stop_with_reason (int cid, int did, int code, const char *reason)
int	am_session_hold (int did, const char *wav_file)
int	am_session_off_hold (int did)
int	am_session_inactive (int did)
int	am_session_inactive_0_0_0_0 (int did)
int	am_session_refresh (int did)
int	am_session_mute (int did)
int	am_session_unmute (int did)
int	am_session_mute_recv (int did, int mute)
int	am_session_set_gain (int did, float out_gain, float in_gain)
int	am_session_refer (int did, const char *url, const char *referred_by)
int	am_session_get_referto (int did, char *refer_to, size_t refer_to_len)
int	am_session_find_by_replaces (osip_message_t *request)
int	am_session_send_notify (int did, const char *sub_state, const char *content_type, const char *body, int size)
int	am_session_send_request (int did, const char *method, const char *content_type, const char *body, int size)
int	am_session_answer_request (int tid, int did, int code)
int	am_session_build_req (int did, const char *method, osip_message_t **request)
int	am_session_send_req (int did, const char *method, osip_message_t *request)
int	am_session_play_file (int did, const char *wav_file)
int	am_session_playfile (int did, const char *wav_file, int repeat, MSFilterNotifyFunc cb_fileplayer_eof, void *userdata)
int	am_session_record (int did, const char *recfile)
int	am_session_stop_record (int did)
int	am_session_send_rtp_dtmf (int did, char dtmf_number)
int	am_session_send_inband_dtmf (int did, char dtmf_number)
int	am_session_send_dtmf (int did, char dtmf_number)
int	am_session_send_dtmf_with_duration (int did, char dtmf_number, int duration)
int	am_session_get_dtmf_event (int did, struct am_dtmf_event *dtmf_event)
int	am_session_get_audio_remote (int did, char *remote_info)
int	am_session_get_audio_bandwidth (int did, struct am_bandwidth_stats *band_stats)
int	am_session_get_video_bandwidth (int did, struct am_bandwidth_stats *band_stats)
int	am_session_get_screensharing_bandwidth (int did, struct am_bandwidth_stats *band_stats)
int	am_session_get_dataevents_bandwidth (int did, struct am_bandwidth_stats *band_stats)
int	am_session_get_udpftp_bandwidth (int did, struct am_bandwidth_stats *band_stats)
int	am_session_get_text_bandwidth (int did, struct am_bandwidth_stats *band_stats)
OrtpEvent *	am_session_get_audio_rtp_events (int did)
OrtpEvent *	am_session_get_video_rtp_events (int did)
int	am_session_release_rtp_events (OrtpEvent *evt)
int	am_session_adapt_audio_bitrate (int did, int percent)
int	am_session_adapt_video_bitrate (int did, int percent)
int	am_session_modify_bitrate (int did, const char *preferred_codec, int compress_more)
int	am_session_set_audio_zrtp_sas_verified (int did)
int	am_session_set_video_zrtp_sas_verified (int did)
int	am_session_reject_video (int did, int _reject_video)
int	am_session_add_video (int did)
int	am_session_stop_video (int did)
int	am_session_send_vfu (int did)
int	am_session_add_t140 (int did)
int	am_session_get_text (int did, MST140Block *_blk)
int	am_session_send_text (int did, MST140Block *_blk)
int	am_session_get_dataevents (int did, MST140Block *_blk)
int	am_session_send_dataevents (int did, MST140Block *_blk)
void	am_free_t140block (MST140Block *_blk)
int	am_session_receive_file (int cid, int did, const char *filename)
int	am_session_file_info (int cid, int did, struct am_fileinfo *fileinfo)
int	am_session_send_file (int cid, int did, const char *filename, const char *filename_short)
int	am_session_stop_transfer (int cid, int did)
int	am_session_get_udpftp (int did, MST140Block *_blk)
int	am_session_send_udpftp (int did, MST140Block *_blk)
int	am_session_video_get_pin (int did)
int	am_session_video_set_pin (int did, int new_pin)
int	am_session_conference_detach (int cid, int did)
int	am_session_conference_attach (int conf_id, int cid, int did)

Detailed Description

Function Documentation

am_session_start_media()

int am_session_start_media	(	const char *	identity,
		const char *	url,
		const char *	proxy,
		const char *	route,
		enum am_media_type *	media_types
	)

Configure amsip to start a SIP session with media (audio, video, text, udpftp).

Parameters

identity	Caller SIP identity
url	Callee SIP identity
proxy	Set the proxy server
route	Set the outbound proxy server
media_types	media_types list

am_session_start()

int am_session_start	(	const char *	identity,
		const char *	url,
		const char *	proxy,
		const char *	route
	)

Configure amsip to start a SIP session.

Parameters

identity	Caller SIP identity
url	Callee SIP identity
proxy	Set the proxy server
route	Set the outbound proxy server

am_session_start_with_video()

int am_session_start_with_video	(	const char *	identity,
		const char *	url,
		const char *	proxy,
		const char *	route
	)

Configure amsip to start a SIP session with video.

Parameters

identity	Caller SIP identity
url	Callee SIP identity
proxy	Set the proxy server
route	Set the outbound proxy server

am_session_start_screensharing()

int am_session_start_screensharing	(	const char *	identity,
		const char *	url,
		const char *	proxy,
		const char *	route
	)

Configure amsip to start a SIP session with screensharing.

Parameters

identity	Caller SIP identity
url	Callee SIP identity
proxy	Set the proxy server
route	Set the outbound proxy server

am_session_start_dataevents()

int am_session_start_dataevents	(	const char *	identity,
		const char *	url,
		const char *	proxy,
		const char *	route
	)

Configure amsip to start a SIP session with dataevents.

Parameters

identity	Caller SIP identity
url	Callee SIP identity
proxy	Set the proxy server
route	Set the outbound proxy server

am_session_answer()

int am_session_answer	(	int	tid,
		int	did,
		int	code,
		int	enable_audio
	)

Configure amsip to answer an INVITE.

Parameters

tid	Transaction identifier.
did	Session identifier.
code	Code to use.
enable_audio	start audio if available.

am_session_conference_answer()

int am_session_conference_answer	(	int	conf_id,
		int	tid,
		int	did,
		int	code,
		int	enable_audio
	)

Configure amsip to answer an INVITE.

Parameters

conf_id	Conference room number (below #define AMSIP_CONF_MAX)
tid	Transaction identifier.
did	Session identifier.
code	Code to use.
enable_audio	start audio if available.

am_session_answer_with_video()

int am_session_answer_with_video	(	int	tid,
		int	did,
		int	code,
		int	enable_audio,
		int	enable_video
	)

Configure amsip to answer an INVITE and accept or reject video.

Parameters

tid	Transaction identifier.
did	Session identifier.
code	Code to use.
enable_audio	start audio if available.
enable_video	start video if available.

am_session_conference_answer_with_video()

int am_session_conference_answer_with_video	(	int	conf_id,
		int	tid,
		int	did,
		int	code,
		int	enable_audio,
		int	enable_video
	)

Configure amsip to answer an INVITE and accept or reject video.

Parameters

conf_id	Conference room number (below #define AMSIP_CONF_MAX)
tid	Transaction identifier.
did	Session identifier.
code	Code to use.
enable_audio	start audio if available.
enable_video	start video if available.

am_session_redirect()

int am_session_redirect	(	int	tid,
		int	did,
		int	code,
		const char *	url
	)

Configure amsip to redirect a SIP session.

Parameters

tid	Transaction identifier.
did	Session identifier.
code	Code to use.
url	SIP (or other url) address for redirection.

am_session_stop()

int am_session_stop	(	int	cid,
		int	did,
		int	code
	)

Configure amsip to stop a SIP session.

Parameters

cid	dialog identifier.
did	Session identifier.
code	Code to use (if answer needed).

am_session_stop_with_reason()

int am_session_stop_with_reason	(	int	cid,
		int	did,
		int	code,
		const char *	reason
	)

Configure amsip to stop a SIP session.

Parameters

cid	dialog identifier.
did	Session identifier.
code	Code to use (if answer needed).
reason	Reason header (optionnal).

am_session_hold()

int am_session_hold	(	int	did,
		const char *	wav_file
	)

Configure amsip to put on hold a SIP session. (send wav_file)

Parameters

did	Session identifier.
wav_file	Wav file to play.

am_session_off_hold()

int am_session_off_hold

(

int

did

)

Configure amsip to put off hold a SIP session.

Parameters

did	Session identifier.

am_session_inactive()

int am_session_inactive

(

int

did

)

Configure amsip to make streams inactive.

Parameters

did	Session identifier.

am_session_inactive_0_0_0_0()

int am_session_inactive_0_0_0_0

(

int

did

)

Configure amsip to make streams inactive. Note: put ip=0_0_0_0 and port=0 for the audio SDP media block. Note2: THIS IS NOT POSSIBLE TO RETREIVE BACK THIS CALL. THIS METHOD MUST ONLY BE USED BEFORE MAKING A CALL TRANSFER WITH SOME UNCOMPLIANT SIP-PBX.

Parameters

did	Session identifier.

am_session_refresh()

int am_session_refresh

(

int

did

)

Configure amsip to refresh a SIP session. This method just send a new INVITE with previous SDP unchanged.

Parameters

did	Session identifier.

am_session_mute()

int am_session_mute

(

int

did

)

Configure amsip to mute a SIP session. (send silence)

Parameters

did	Session identifier.

am_session_unmute()

int am_session_unmute

(

int

did

)

Configure amsip to unmute a SIP session.

Parameters

did	Session identifier.

am_session_mute_recv()

int am_session_mute_recv	(	int	did,
		int	mute
	)

Configure amsip to mute/unmute incoming audio for a SIP session.

Parameters

did	Session identifier.
mute	0 to disable, 1 to enable.

am_session_set_gain()

int am_session_set_gain	(	int	did,
		float	out_gain,
		float	in_gain
	)

Configure amsip to set channel gain in a SIP session. THIS IS NOT IMPLEMENTED IN AMSIP SDK (Available under other engine.)

Parameters

did	Session identifier.
out_gain	Channel speaker gain
in_gain	Channel mic gain

am_session_refer()

int am_session_refer	(	int	did,
		const char *	url,
		const char *	referred_by
	)

Configure amsip to transfer a SIP session.

Parameters

did	Session identifier.
url	SIP (or other url) address for redirection.
referred_by	SIP address for Referred-By

am_session_get_referto()

int am_session_get_referto	(	int	did,
		char *	refer_to,
		size_t	refer_to_len
	)

Add Replaces parameter to refer-to url.

Parameters

did	Session identifier.
refer_to	String to carry refer_to.
refer_to_len	Size of refer_to string.

am_session_find_by_replaces()

int am_session_find_by_replaces

(

osip_message_t *

request

)

Find the call that relates to the Replaces header.

Parameters

request

requet containging a replace header.

am_session_send_notify()

int am_session_send_notify	(	int	did,
		const char *	sub_state,
		const char *	content_type,
		const char *	body,
		int	size
	)

Send a request during a session

Parameters

did	Session identifier.
sub_state	Subscription-State parameter.
content_type	Content-type of the body
body	Attached content
size	Size of body

am_session_send_request()

int am_session_send_request	(	int	did,
		const char *	method,
		const char *	content_type,
		const char *	body,
		int	size
	)

Send a request during a session

Parameters

did	Session identifier.
method	SIP method (e.g. INVITE).
content_type	Content-type of the body.
body	Attached content.
size	Size of body.

am_session_answer_request()

int am_session_answer_request	(	int	tid,
		int	did,
		int	code
	)

Configure amsip to establish a SIP session.

Parameters

tid	Transaction identifier.
did	Session identifier.
code	Code to use.

am_session_build_req()

int am_session_build_req	(	int	did,
		const char *	method,
		osip_message_t **	request
	)

Send a request during a session (NOTE: NOT FOR INVITE, ACK, BYE, CANCEL)

Parameters

did	Session identifier.
method	SIP method (e.g. MESSAGE, REFER, NOTIFY, INFO...)
request	pointer to a request being filled.

am_session_send_req()

int am_session_send_req	(	int	did,
		const char *	method,
		osip_message_t *	request
	)

Send a request during a session (NOTE: NOT FOR INVITE, ACK, BYE, CANCEL)

Parameters

did	Session identifier.
method	SIP method (e.g. MESSAGE, REFER, NOTIFY, INFO...)
request	request message to send.

am_session_play_file()

int am_session_play_file	(	int	did,
		const char *	wav_file
	)

Configure amsip to play a file in an outgoing RTP session.

Parameters

did	Session identifier.
wav_file	File to play.

am_session_playfile()

int am_session_playfile	(	int	did,
		const char *	wav_file,
		int	repeat,
		MSFilterNotifyFunc	cb_fileplayer_eof,
		void *	userdata
	)

Configure amsip to play a file in an outgoing RTP session.

Parameters

did	Session identifier.
wav_file	File to play.
repeat	repeat: -2 to play once, >0 delai between replay.
cb_fileplayer_eof	callback to indicate endoffile.
userdata	pointer for application layer returned in callback.

am_session_record()

int am_session_record	(	int	did,
		const char *	recfile
	)

Record both audio stream (incoming+outgoing).

Parameters

did	Session identifier.
recfile	File Name for recording.

am_session_stop_record()

int am_session_stop_record

(

int

did

)

Stop recording the call.

Parameters

did	Session identifier.

am_session_send_rtp_dtmf()

int am_session_send_rtp_dtmf	(	int	did,
		char	dtmf_number
	)

Configure amsip to send a RTP telephone-event in an outgoing RTP session.

Parameters

did	Session identifier.
dtmf_number	DTMF to send.

am_session_send_inband_dtmf()

int am_session_send_inband_dtmf	(	int	did,
		char	dtmf_number
	)

Configure amsip to send an in-band DTMF in an outgoing RTP session.

Parameters

did	Session identifier.
dtmf_number	DTMF to send.

am_session_send_dtmf()

int am_session_send_dtmf	(	int	did,
		char	dtmf_number
	)

Configure amsip to send an INFO with dtmf attachement.

Parameters

did	Session identifier.
dtmf_number	DTMF to send.

am_session_send_dtmf_with_duration()

int am_session_send_dtmf_with_duration	(	int	did,
		char	dtmf_number,
		int	duration
	)

Configure amsip to send an INFO with dtmf attachement.

Parameters

did	Session identifier.
dtmf_number	DTMF to send.
duration	DTMF duration.

am_session_get_dtmf_event()

int am_session_get_dtmf_event	(	int	did,
		struct am_dtmf_event *	dtmf_event
	)

Get dtmf from RTP session.

Parameters

did	Session identifier.
dtmf_event	dtmf_event structure.

am_session_get_audio_remote()

int am_session_get_audio_remote	(	int	did,
		char *	remote_info
	)

Find out the destination IP/PORT for audio stream. return >0 remote SDP ip/port used return ==0 remote SDP candidate ip/port used (probably for direct comunication) return <0 undefined error.

Parameters

did	Session identifier.
remote_info	string of size 256 to get the remote IP/PORT for audio stream.

am_session_get_audio_bandwidth()

int am_session_get_audio_bandwidth	(	int	did,
		struct am_bandwidth_stats *	band_stats
	)

Get statistics for RTP audio stream.

Parameters

did	Session identifier.
band_stats	struct to hold information.

am_session_get_video_bandwidth()

int am_session_get_video_bandwidth	(	int	did,
		struct am_bandwidth_stats *	band_stats
	)

Get statistics for RTP video stream.

Parameters

did	Session identifier.
band_stats	struct to hold information.

am_session_get_screensharing_bandwidth()

int am_session_get_screensharing_bandwidth	(	int	did,
		struct am_bandwidth_stats *	band_stats
	)

Get statistics for RTP screensharing stream.

Parameters

did	Session identifier.
band_stats	struct to hold information.

am_session_get_dataevents_bandwidth()

int am_session_get_dataevents_bandwidth	(	int	did,
		struct am_bandwidth_stats *	band_stats
	)

Get statistics for RTP dataevents stream.

Parameters

did	Session identifier.
band_stats	struct to hold information.

am_session_get_udpftp_bandwidth()

int am_session_get_udpftp_bandwidth	(	int	did,
		struct am_bandwidth_stats *	band_stats
	)

Get statistics for RTP udpftp stream.

Parameters

did	Session identifier.
band_stats	struct to hold information.

am_session_get_text_bandwidth()

int am_session_get_text_bandwidth	(	int	did,
		struct am_bandwidth_stats *	band_stats
	)

Get statistics for RTP text stream.

Parameters

did	Session identifier.
band_stats	struct to hold information.

am_session_get_audio_rtp_events()

OrtpEvent* am_session_get_audio_rtp_events

(

int

did

)

Get RTP events (DTMF, RTCP...) on audio stream

Parameters

did	Session identifier.

am_session_get_video_rtp_events()

OrtpEvent* am_session_get_video_rtp_events

(

int

did

)

Get RTP events (DTMF, RTCP...) on video stream

Parameters

did	Session identifier.

am_session_release_rtp_events()

int am_session_release_rtp_events

(

OrtpEvent *

evt

)

Release allocated RTP events.

Parameters

evt	Event to release.

am_session_adapt_audio_bitrate()

int am_session_adapt_audio_bitrate	(	int	did,
		int	percent
	)

Configure amsip to modify audio bitrate when possible in a session. Note: this feature only work with adaptative codec, technical implementation may differ between codecs.

Parameters

did	Session identifier.
percent	between 0 and 100 to decrease, above 100 to increase.

am_session_adapt_video_bitrate()

int am_session_adapt_video_bitrate	(	int	did,
		int	percent
	)

Adapt video bitrate in the call.

Parameters

did	Session identifier.
percent	between 0 and 100 to decrease, above 100 to increase.

am_session_modify_bitrate()

int am_session_modify_bitrate	(	int	did,
		const char *	preferred_codec,
		int	compress_more
	)

Get statistics for RTP audio stream.

Parameters

did	Session identifier.
preferred_codec	Preferred codec to use.
compress_more	compress_more. (0 means you want to use more bandwidth)

am_session_set_audio_zrtp_sas_verified()

int am_session_set_audio_zrtp_sas_verified

(

int

did

)

Confirm ZRTP SAS for audio stream has been verified.

Parameters

did	Session identifier.

am_session_set_video_zrtp_sas_verified()

int am_session_set_video_zrtp_sas_verified

(

int

did

)

Confirm ZRTP SAS for video stream has been verified.

Parameters

did	Session identifier.

am_session_reject_video()

int am_session_reject_video	(	int	did,
		int	_reject_video
	)

Reject any incoming video negotiation by setting port to 0 in SDP.

Parameters

did	Session identifier.
_reject_video	0 to not reject, >0 to reject.

am_session_add_video()

int am_session_add_video

(

int

did

)

Add video in the call.

Parameters

did	Session identifier.

am_session_stop_video()

int am_session_stop_video

(

int

did

)

Disable video in the call.

Parameters

did	Session identifier.

am_session_send_vfu()

int am_session_send_vfu

(

int

did

)

Send VFU in the video call.

Parameters

did	Session identifier.

am_session_add_t140()

int am_session_add_t140

(

int

did

)

Add t140 chat session in the call.

Parameters

did	Session identifier.

am_session_get_text()

int am_session_get_text	(	int	did,
		MST140Block *	_blk
	)

Get UDP/RTP text from remote party.

Parameters

did	Session identifier.
_blk	Block that contains text data.

am_session_send_text()

int am_session_send_text	(	int	did,
		MST140Block *	_blk
	)

Send UDP/RTP text from remote party.

Parameters

did	Session identifier.
_blk	Block that contains text data.

am_session_get_dataevents()

int am_session_get_dataevents	(	int	did,
		MST140Block *	_blk
	)

Get UDP/RTP dataevents from remote party.

Parameters

did	Session identifier.
_blk	Block that contains text data.

am_session_send_dataevents()

int am_session_send_dataevents	(	int	did,
		MST140Block *	_blk
	)

Send UDP/RTP dataevents from remote party.

Parameters

did	Session identifier.
_blk	Block that contains text data.

am_free_t140block()

void am_free_t140block

(

MST140Block *

_blk

)

Release allocated string inside MST140Block.

Parameters

_blk	Block that contains text data.

am_session_receive_file()

int am_session_receive_file	(	int	cid,
		int	did,
		const char *	filename
	)

Receive file within a udpftp (t140) established call.

Parameters

cid	Session identifier.
did	Session identifier.
filename	filename of the file to receive.

am_session_file_info()

int am_session_file_info	(	int	cid,
		int	did,
		struct am_fileinfo *	fileinfo
	)

Receive file within a udpftp established call.

Parameters

cid	Session identifier.
did	Session identifier.
fileinfo	information about file transfer.

am_session_send_file()

int am_session_send_file	(	int	cid,
		int	did,
		const char *	filename,
		const char *	filename_short
	)

Send file information within a udpftp established call.

Parameters

cid	Session identifier.
did	Session identifier.
filename	filename (with path) of the file to send.
filename_short	filename (without path) of the file to send.

am_session_stop_transfer()

int am_session_stop_transfer	(	int	cid,
		int	did
	)

Release udpftp transfer resources.

Parameters

cid	Session identifier.
did	Session identifier.

am_session_get_udpftp()

int am_session_get_udpftp	(	int	did,
		MST140Block *	_blk
	)

Get UDP/RTP data from remote party.

Parameters

did	Session identifier.
_blk	Block that contains text data.

am_session_send_udpftp()

int am_session_send_udpftp	(	int	did,
		MST140Block *	_blk
	)

Send UDP/RTP data from remote party.

Parameters

did	Session identifier.
_blk	Block that contains text data.

am_session_video_get_pin()

int am_session_video_get_pin

(

int

did

)

Get the video stitcher pin for a video call.

Parameters

did	Session identifier.

am_session_video_set_pin()

int am_session_video_set_pin	(	int	did,
		int	new_pin
	)

Set the video stitcher pin for a video call. If another call is already on new_pin, the pin will be exchanged.

Parameters

did	Session identifier.
new_pin	New pin for video call.

am_session_conference_detach()

int am_session_conference_detach	(	int	cid,
		int	did
	)

Disconnect a call to a conference.

THE CALL MUST NEVER BE ATTACHED TO A CONFERENCE AGAIN. If you wish to move a call to another conference, use "am_session_conference_attach" API.

Parameters

cid	dialog identifier.
did	Session identifier.

am_session_conference_attach()

int am_session_conference_attach	(	int	conf_id,
		int	cid,
		int	did
	)

Connect a call from a conference.

Parameters

conf_id	Conference room number (below #define AMSIP_CONF_MAX)
cid	dialog identifier.
did	Session identifier.