Creating a new Providerbackend for Iro

See also class documentation iro.offer.provider.Provider.

A very simple provider

For testing purpose it is nice to create a small provider.

from iro.offer import providers, Provider

class TestProvider(Provider):
    def __init__(self,name):
        Provider.__init__(self, name, {"sms" : ["a",]})

providers["myveryspecialProvider"] = TestProvider

• line 3 – a Provider that supports message type sms, and has one route named a.

• line 5 – register the provider type TestProvider in the global providers dict. Following section in configuraton file will create a new TestProvider object, with name="blablub":

  [blablub]
  #see line 5
  typ = myveryspecialProvider
  

Normally a new Provider wants to have extra options for configuration file:

from iro.offer import providers, Provider
from iro.config import Option

def validater(value, field):
    return value

class TestProvider(Provider):
    def __init__(self,name):
        options =[("key", Option(validater,long="My Option explanation", must=True)),]
        Provider.__init__(self, name, {"sms" : ["a",]}, options)

providers["myveryspecialProvider"] = TestProvider

in line 9 we create a item list ( [(name,Option),...] – more information about iro.config.Option). validater have to be a function that returns value, if the value is valid. With this following section in configuration file is possible:

[balblub]
typ = myveryspecialProvider
#My Option explanation
key = mykey

Ok, now we know to get settings into the provider. But we have to do anything, when user want to send anything. So we have to create a send function.

Creating sipgate provider

Sipgate supports sending sms and faxes via XML-RPC. so it is easy to create a new providerbackend for iro via sipgate. First we get the XML-RPC Api documention for sipgate (http://www.sipgate.de/beta/public/static/downloads/basic/api/sipgate_api_documentation.pdf). Sipgate uses HTTP Basic Authentification, that’s we he create to options for our sipgate provider:

from iro.offer import providers, Provider
from iro.config import Option

class Sipgate(Provider):
    def __init__(self,name):
        options =[("username", Option(lambda x,y: x,long="Loginname for sipgate", must=True)),
                  ("password", Option(lambda x,y: x,long="Password for sipgate", must=True)),]
        Provider.__init__(self, name, {"sms" : [None], "fax":[None]}, options)

providers["sipgate"] = Sipgate

• line 6/7 – we don’t have any ideas what is allowed as username/password, so we create a validator that accepts everything.
• line 8 – sipgate supports fax and sms, but now diffrent routes, that’s we use None.

Now we have to possible options to implement the send function. either we implement a blocking interface or use the recommended solution: twisted non blocking solution. We show here the recommended version.

The Twisted Way (recommended solution)

First we start to implement the fax and sms methods:

def proxy(self):
    return Proxy("https://%s:%s@samurai.sipgate.net/RPC2"%(self.username, self.password))

def sms(self, recipient, sms):
    args={
            "TOS" : "text",
            "Content" : sms.getContent(),
            "RemoteUri" : "sip:%s%s@sipgate.net"%(recipient.land, recipient.number),
            }
    return self.proxy().callRemote("samurai.SessionInitiate",args)

def fax(self, recipient, fax):
    args={
        "TOS" : "fax",
        "Content" : xmlrpclib.Binary(fax.getAttachment(0)),
        "RemoteUri" : "sip:%s%s@sipgate.net"%(recipient.land, recipient.number),
        }
    return self.proxy().callRemote("samurai.SessionInitiate",args)

The code is straight forward with the API documentation from sipgate. Now we have to implement the heat of the provider the send method:

def _status(self,value,typ):
    if typ not  in self.typs.keys():
        raise NoTyp(typ)
    return Status(self, None, Decimal("1.00"), 1, value["SessionID"])

def send(self, typ, recipient, msg):
    if typ not  in self.typs.keys():
        raise NoTyp(typ)
    d = getattr(self,typ)(recipient, msg)
    d.addCallback(self._status, typ)
    return d

def getSendFunc(self, typ, route):
    """returns :meth:`send` method, if typ and route is valid."""

    Provider.getSendFunc(self, typ, route)
    return partial(self.send, typ)

Because sipgate doesn’t support different routes, we implement a send function without route argument. That’s why we have to rewrite the getSendFunc method. It now returns a partial function with only a binded typ.

The send method first test the for a valid typ (line 7/8), than it execute the sms or fax method. For a valid provider we have to return a Status object. There for we add a callback that returns a Status object (see _status method).

Unfortunatelly sipgate doesn’t support methods to get the price for one action. So we have to set set a fixed price here Decimal('1.00'). In the wild we implement new configuration parameters for priceing.

Now the provider is ready to use. For complete source of this tutorial see iro.offer.sipgate.