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`.