The SIP property¶

SIP (Session Initiation Protocol) is a signalling communications protocol used for controlling communication, such as voice calls, over IP (Internet Protocol) networks. The UAS API provides methods that grant access to some SIP features. Please refer to the online cloud documentation for updates.

Please familiarise yourself with the SIP specific functionality before using the SIP property.

class HeaderFieldsToSend¶

A list of SIPHeaderField objects. The channel.call() and channel.answer() functions will look in this list for SIP Headers Fields to send. Append or remove SIPHeaderField objects from this list before answering or placing a call.

Usage example:

channel.SIP.HeaderFieldsToSend.append(SIPHeaderField("x-Authorization", "me@my.place"))

class SIPHeaderField(header_field_name, header_value)¶

Used when sending and receiving SIP Header fields.

Required argument:

header_field_name
the SIP Header name.
header_value
the SIP Header value.

Valid SIP Header field-name characters are a to z; A to Z; 0 to 9 and -.!%*_+`'~

At the time of writing, this class supports only custom headers, i.e., those that begin with x-. Please refer to the online documentation for updates.

Usage example:

from prosody.uas import SIPHeaderField

channel.SIP.HeaderFieldsToSend.append(SIPHeaderField("x-Authorization", "me@my.place"))

add_value(header_value)¶

Add a header value to this header field.

Usage example:

from prosody.uas import SIPHeaderField

my_header_field = SIPHeaderField("x-Authorization", "me@my.place")
my_header_field.add_value("you@my.place")
channel.SIP.HeaderFieldsToSend.append(my_header_field)

get_name()¶

Returns the header name.

Usage example:

sip_header_field = channel.SIP.request_header_field("x-Authorization")
if sip_header_field:
    print("Have header: {0}".format(sip_header_field.get_name()))

get_values()¶

Returns a list of header field values.

Usage example:

sip_header_field = channel.SIP.request_header_field("x-Authorization")
if sip_header_field:
    print("Have header values: {0}".format(sip_header_field.get_values()))

class SIPInfo(body, content_type=None)¶

The purpose of the SIP INFO method is to carry application level information between endpoints, using the SIP dialogue signalling path.

This class is used when sending and receiving SIP INFO.

At the time of writing, this class is not yet supported on Aculab Cloud. Please refer to the online documentation for updates.

Required argument:

body
the SIP INFO body.

Optional argument:

content_type
the SIP INFO content type.

If content_type is not supplied the following default behaviour will apply:

If body is a Unicode string, it will be UTF-8 encoded and content_type will be set to text/plain; charset=UTF-8.

If body is a string content_type will be set to text/plain; charset=ascii.

If body is a single character in the set 0 1 2 3 4 5 6 7 8 9 A B C D * #, content_type will be set to "application/dtmf-relay" and a DTMF package will be sent with duration set to 250 milliseconds.

Usage example:

from prosody.uas import SIPInfo

channel.SIP.send(SIPInfo("Aculab Cloud SIP INFO", "text/plain; charset=ascii"))

get_body()¶

Returns the SIP INFO body.

Usage example:

sip_infos = channel.SIP.get_infos()
if sip_infos:
    print("Have SIP INFO: {0}".format(sip_infos[0].get_body()))

get_content_type()¶

Returns the SIP INFO content type.

Usage example:

sip_infos = channel.SIP.get_infos()
if sip_infos:
    print("Have SIP INFO with content type: {0}".format(sip_info[0].get_content_type()))

class SIPInfoDTMFRelay(digit, milliseconds_duration=250)¶

A helper class for sending a SIP INFO DTMF package.

At the time of writing, this class is not yet supported on Aculab Cloud. Please refer to the online documentation for updates.

Required argument:

digit
the DTMF digit to send, one of 0 1 2 3 4 5 6 7 8 9 A B C D * #.
milliseconds_duration
the DTMF digit duration, from 100 to 5000 milliseconds. Default it 250.

Usage example:

from prosody.uas import SIPInfoDTMFRelay

channel.SIP.send(SIPInfoDTMFRelay("5", "500"))

class SIPInfoPlainText(text)¶

A helper class for sending a SIP INFO plain text package.

At the time of writing, this class is not yet supported on Aculab Cloud. Please refer to the online documentation for updates.

Required argument:

text
the text to send.

Usage example:

from prosody.uas import SIPInfoPlainText

channel.SIP.send(SIPInfoPlainText("Aculab Cloud SIP INFO"))

class SIPMessage(body, content_type=None)¶

The purpose of the SIP MESSAGE method is for sending instant messages. Instant Messaging (IM) is defined as the exchange of content between a set of participants in near real time. Generally, the content is short text messages.

Used when sending and receiving SIP MESSAGEs.

At the time of writing, this class is not yet supported on Aculab Cloud. Please refer to the online documentation for updates.

Required argument:

body
the SIP MESSAGE body.

Optional argument:

content_type
the SIP MESSAGE content type.

If body is a Unicode string, it will be UTF-8 encoded and content_type will be set to text/plain; charset=UTF-8.

If body is a string and content_type is not specified, content_type will be set to text/plain; charset=ascii.

Usage example:

from prosody.uas import SIPMessage

channel.SIP.send(SIPMessage("Aculab Cloud SIP MESSAGE", "text/plain; charset=ascii"))

get_body()¶

Returns the SIP MESSAGE body.

Usage example:

sip_messages = channel.SIP.get_messages()
if sip_messages:
    print("Have SIP INFO: {0}".format(sip_messages[0].get_body()))

get_content_type()¶

Returns the SIP MESSAGE content type.

Usage example:

sip_message = channel.SIP.get_message()
if sip_message:
    print("Have SIP MESSAGE with content type: {0}".format(sip_message.get_content_type()))

class SIPMessagePlainText(text)¶

A helper class for sending a SIP MESSAGE plain text package.

At the time of writing, this class is not yet supported on Aculab Cloud. Please refer to the online documentation for updates.

Required argument:

text
the text to send.

Usage example:

from prosody.uas import SIPMessagePlainText

channel.SIP.send(SIPMessagePlainText("Aculab Cloud SIP MESSAGE"))

class UASCallSIP(server, call, logger, ID)¶

Exposed by the call channel object to enable sending and retrieving SIP INFO, MESSAGE and Header Fields.

The call channel object has a public property called SIP of this type.

Inbound SIP INFO and MESSAGE packages are received and buffered by the UAS as they come in. These packages can be retrieved by the application at any time. The buffer is cleared when packages are retrieved but can fill with more packages if they arrive.

Usage example:

# get all the SIP MESSAGEs that have arrived so far
sip_messages = channel.SIP.get_messages()

class State¶

The SIP state can be checked to determine it is busy or not.

SIP states are:

BUSY: A SIP INFO or MESSAGE is being sent.
IDLE: SIP is not being sent.
ERROR: An error has occurred.

Usage example:

state = channel.SIP.state()
if state == channel.SIP.State.BUSY:
    # SIP is being sent
    pass

get_infos()¶

Get all the SIP INFOs received so far.

Returns a list of SIPInfo objects. If no SIP INFO objects are available an empty list is returned.

Usage example:

sip_infos = channel.SIP.get_infos()

get_messages()¶

Get all the MESSAGEs received so far.

Returns a list of SIPMessage objects. If no SIP MESSAGEs are available an empty list is returned.

Usage example:

sip_messages = channel.SIP.get_messages()

request_header_field(header_field_name)¶

Where header_field_name is the name of the SIP Header Field to get.

The call must be in the ANSWERED state otherwise a Hangup exception will be raised.

Returns a SIPHeaderField object that matches header_field_name. If there is no match None is returned.

Usage example:

sip_headers = channel.SIP.request_header_field("x-Authorization")

send(sip_object)¶

Send a SIP MESSAGE or SIP INFO object, the parameter sip_object can be any SIPMessage or SIPInfo object.

The call must be in the ANSWERED state otherwise a Hangup exception will be raised.

Returns a SIP code string, e.g., “200”.

Usage example:

sip_message = SIPMessagePlainText("Hello World")
sip_code = channel.SIP.send(sip_message)

state()¶

Return the SIP state.

Usage example:

if channel.SIP.state() == channel.SIP.State.BUSY:
    # channel.SIP is sending data
    pass

The SIP property¶

Previous topic

Next topic