Creating a new Providerbackend for Iro
======================================

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

A very simple provider 
----------------------

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

.. code-block:: python
    :linenos:
    
    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:

.. code-block:: python
    :linenos:
    
    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 :class:`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:

.. code-block:: python
    :linenos:

    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:

.. code-block:: python
    :linenos:
    
    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:

.. code-block:: python
    :linenos:

    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 :class:`~iro.model.status.Status` object.
There for we add a callback that returns a :class:`~iro.model.status.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 :class:`iro.offer.sipgate`.