exosip2ctypes.context module

eXosip2 context API

class exosip2ctypes.context.Context(event_callback=None)

Bases: exosip2ctypes.context.BaseContext, exosip2ctypes.utils.LoggerMixin

Allocate and Initiate an eXosip context.

Parameters:event_callback (callable) –

Event callback.

It’s a callback function or any other callable object. You can avoid the parameter in constructor, and set event_callback later.

The callback is like:

def event_callback(context, event):
    # do some thing...
    pass
It has two parameters:
  • Context : eXosip context on which the event happened.
  • Event : The event happened.
add_authentication_info(user_name, user_id, password, realm)

Add authentication credentials.

Parameters:
  • user_name (str) – username
  • user_id (str) – login (usually equals the username)
  • password (str) – password
  • realm (str) – realm within which credentials apply, or None to apply credentials to unrecognized realms

These are used when an outgoing request comes back with an authorization required response.

automatic_action()

Initiate some automatic actions:

  • Retry with credentials upon reception of 401/407.
  • Retry with higher Sessions-Expires upon reception of 422.
  • Refresh REGISTER and SUBSCRIBE before the expiration delay.
  • Retry with Contact header upon reception of 3xx request.
  • Send automatic UPDATE for session-timer feature.
build_message(message_class, *args, **kwargs)

Build a default message for a eXosip transaction/dialog/call

Parameters:
  • message_class (type(ExosipMessage)) – Message Class
  • args – Sequent arguments passed to the class constructor
  • kwargs – Named arguments passed to the class constructor
Returns:

New built message object

Return type:

ExosipMessage

call_send_ack(did=None, ack=None)

Send the ACK for the 200ok received.

Parameters:
  • did (int) – dialog id of call.
  • ack (call.Ack) – SIP ACK message to send. did won’t be used if specified.
call_send_answer(tid=None, status=None, answer=None)

Send Answer for invite.

Parameters:
  • tid (int) – id of transaction to answer.
  • status (int) – response status if answer is NULL. (not allowed for 2XX)
  • answer (call.Answer) – The sip answer to send. tid and status won’t be used if specified.
call_send_init_invite(invite)

Initiate a call.

Parameters:invite (call.InitInvite) – SIP INVITE message to send.
Returns:CID - unique id for SIP calls (but multiple dialogs!)
Return type:int

Attention

returned call id is an integer, which different from SIP message’s Call-Id header

call_terminate(cid, did=0)

Terminate a call. send CANCEL, BYE or 603 Decline.

Parameters:
  • cid (int) – call id of call.
  • did (int) – dialog id of call.
event_callback

Set event callback

Return type:callable

Attention

Event callback is invoked in a concurrent.futures.Executor

event_wait(s, ms)

Wait for an eXosip event.

Parameters:
  • s (int) – timeout value (seconds).
  • ms (int) – timeout value (seconds).
Returns:

event or None if no event

Return type:

Event

get_event_callback()

Set event callback

Return type:callable

Attention

Event callback is invoked in a concurrent.futures.Executor

is_running

Is the context’s main loop running

Return type:bool
listen_on_address(address=None, transport=17, port=5060, family=<AddressFamily.AF_INET: 2>, secure=False)

Listen on a specified socket.

Parameters:
  • address (str) – the address to bind (NULL for all interface)
  • transport (int) – socket.IPPROTO_UDP for udp. (soon to come: TCP/TLS?)
  • port (int) – the listening port. (0 for random port)
  • family (int) – the IP family (socket.AF_INET or socket.AF_INET6).
  • secure (bool) – False for UDP or TCP, True for TLS (with TCP).
lock

eXosip Context lock.

Return type:ContextLock
lock_acquire()

Lock the eXtented oSIP library.

lock_release()

UnLock the eXtented oSIP library.

locked

True if the context has been acquired by some thread, False if not.

Return type:bool
masquerade_contact(public_address=None, port=0)

This method is used to replace contact address with the public address of your NAT. The ip address should be retrieved manually (fixed IP address) or with STUN. This address will only be used when the remote correspondent appears to be on an DIFFERENT LAN.

If set to None, then the local ip address will be guessed automatically (returns to default mode).

Parameters:
  • public_address (str) – the ip address.
  • port (int) – the port for masquerading.

Note

It’s advised to call the method after listen_on_address()

ptr

C Pointer to the context’s eXosip_t C structure

Return type:ctypes.c_void_p
quit()

Release resource used by the eXtented oSIP library.

remove_authentication_info(user_name, realm)

Remove authentication credentials.

Parameters:
run(s=0, ms=50, event_executor=None, timeout=None)

Start the main loop for the context in a create thread, and then wait until the thread terminates.

Parameters:
  • s (int) – timeout value (seconds). Passed to event_wait() in the main loop.
  • ms (int) – timeout value (seconds). Passed to event_wait() in the main loop.
  • event_executor (concurrent.futures.Executor) – see the same parameter in start().
  • timeout (float) – When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof)

This method blocks, it equals:

trd = context.start(s, ms)
trd.join(timeout)
set_event_callback(val)

Set event callback

Parameters:val (callable) – callback function

Attention

Event callback is invoked in a concurrent.futures.Executor

start(s=0, ms=50, event_executor=None)

Start the main loop for the context in a create thread, and then return.

Parameters:
Returns:

New created event loop thread.

Return type:

threading.Thread

This method returns soon after the main loop thread started, so it does not block.

Equal to set is_running to True

stop()

Stop the context’s main loop thread and return after the thread stopped.

Equal to set is_running to False

user_agent

Context’s user agent string

Return type:str
class exosip2ctypes.context.ContextLock(context)

Bases: object

A helper class for eXosip Context lock

This class wraps eXosip’s native context lock function, which is invoked in Context.lock_acquire() and Context.lock_release(). You can call theses methods directly, or use Context.lock.

with statement is supported.

eg:

context.lock.acquire()
try:
    do_something()
    # ...
finally:
    context.lock.release()

or:

with context.lock:
    do_something()
    # ...

Danger

Do NOT construct the class yourself, use Context.lock.

Parameters:context (Context) – Context which the lock is for
acquire()

lock the context

locked()

Return the status of the lock: True if it has been acquired by some thread, False if not.

Return type:bool
release()

unlock the context