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: 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:
-
call_send_ack
(did=None, ack=None)¶ Send the ACK for the 200ok received.
Parameters:
-
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:
-
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: Returns: event or None if no event
Return type:
-
get_event_callback
()¶ Set event callback
Return type: callable Attention
Event callback is invoked in a
concurrent.futures.Executor
-
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
orsocket.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.
-
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: 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: - user_name (str) – user name
- realm (str) – realm must be exact same arg as for
add_authentication_info()
-
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)
- s (int) – timeout value (seconds). Passed to
-
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: - 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) – Event executor instance. Events will be fired in it.
Default is a
concurrent.futures.ThreadPoolExecutor
instance
Returns: New created event loop thread.
Return type: This method returns soon after the main loop thread started, so it does not block.
Equal to set
is_running
to True- s (int) – timeout value (seconds). Passed to
-
stop
()¶ Stop the context’s main loop thread and return after the thread stopped.
Equal to set
is_running
to False
-
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()
andContext.lock_release()
. You can call theses methods directly, or useContext.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
-