Category:HowTo:XMLRPC Redirection

From Snom User Wiki

Revision as of 11:39, 23 July 2018 by Berterp (Talk | contribs)
Jump to: navigation, search

Author: Sven Fischer Version: 1.2

Contents

IMPORTANT NOTE ABOUT THE REDIRECTION SERVICE STATUS

The Snom RDS (ReDirection Service) has been replaced by the new service called SRAPS (Secure Redirection and Provisioning Service).

SRAPS will offer all the RDS functionalities (Redirection management and XML-RPC APIs) plus various features, first of all security.

At this page you can see the status of the migration process

Protocol

  • The interface between client and server is built as XMLRPC services. To access them you may use XMLRPC libraries available in the internet or do it yourself by sending XML documents described further down via HTTP POST requests using Content-Type: text/xml.
  • TLS is used to encrypt the communication between client and server.
  • User authentication is done via basic authentication.

SRAPS Service Port

The xmlrpc SRAPS API service can be accessed at:

https://secure-provisioning.snom.com:8083/xmlrpc/

User Accounts

In order to access the redirection service you need to have a valid which you can get from Snom following the instructions described here. If you already have an account for the old provisioning shell you should be able to access the new redirection service with it as well, if you informed snom about it before. But it is recommended to request a new account. SSH keys are not supported anymore; you need to use the account password.

Transition

To migrate the MACs of the old accounts to the new one, first login with the old accounts using the XMLRPC service and delete them. Then use the new account to register them again.

Available XMLRPC Commands

redirect.registerPhone

A specific phone (MAC) can be registered at the redirection service in order to redirect it to a different setting server.

XMLRPC signature
redirect.registerPhone(mac, provisioningUrl)

Parameter:

  1. mac: MAC address the requesting user would like to register to the service.
  2. provisioningUrl: The URL the phone to be registered should be redirected to.

Return values:

  1. Result code: True, False
  2. Result text:
    1. Ok, if the given mac address could be registered successfully to the mac addresses of the requesting user.
    2. Error:owned_by_other_user if the requested mac is already registered to somebody else, Error:malformed_url if the given provisioningUrl is faulty or Error:malformed_mac if the given MAC is faulty.

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.registerPhone</methodName>

 <params>

  <param>

   <value><string>000413244321</string></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prv2.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

positive Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

negative Answer of Error:owned_by_other_user:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:owned_by_other_user</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.deregisterPhone

A specific registered phone (MAC) can be deregistered from the service.

XMLRPC signature
redirect.deregisterPhone(mac)

Parameter:

  1. mac: MAC address the requesting user would like to deregister from the service.

Return values:

  1. Result code: True, False
  2. Result text:
    1. Ok, if the requesting user owns the given mac address and the mac address could be deregistered successfully.
    2. Error:owned_by_other_user if the requested mac is registered to somebody else or Error:malformed_mac if the given MAC is faulty.

The following snippets are showing examples of the handshake of the above described XMLRPC request.

Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.deregisterPhone</methodName>

 <params>

  <param>

   <value><string>000413244321</string></value>

  </param>

 </params>

</methodCall>

positive Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

negative Answer of Error:owned_by_other_user:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:owned_by_other_user</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>


redirect.getPhoneRedirection

Get the redirection target for a specific mac address.

IMPORTANT: this method has been implemented only on SRAPS, isn't implemented on the redirection server.

XMLRPC signature
redirect.getPhoneRedirection(mac)

Parameter:

  1. mac: MAC address the requesting user would like to get the redirection target.

Return values:

  1. Result code: True, False
  2. Result text:
    1. Ok, and the company and the redirection URL for the mac address
    2. Error:wrong_user if the requested mac is registered to somebody else or Error:malformed_mac if the given MAC is faulty.

The following snippets are showing examples of the handshake of the above described XMLRPC request.

positive Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>
    
    <value><string>Snom Technology GmbH</string></value>
    
    <value><string>http://my.provisioning.com/snom/${mac]</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>
Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.getPhoneRedirection</methodName>

 <params>

  <param>

   <value><string>000413244321</string></value>

  </param>

 </params>

</methodCall>
negative Answer of Error:owned_by_other_user:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:owned_by_other_user</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.listPhones

A list including all registered phones (MACs) of the requesting user is provided.

XMLRPC signature
redirect.listPhones(phoneType, provisioningUrl=None)

Parameter:

  1. phoneType: type of phone of which the requesting user wants to see the list of the phones he has already registered.
  2. provisioningUrl: optional URL matching the already redirected MACs of the requesting user.

Return values:

  1. Result: a list of mac addresses the requesting user has registered, an empty list otherwise.

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.listPhones</methodName>

 <params>

  <param>

   <value><string>snom360</string></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prov.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

Filled Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><string>000413230c25</string></value>

    <value><string>000413230c24</string></value>

    <value><string>000413230c23</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Empty Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.checkPhone

Checks if a phone (MAC) is registered to the requesting user.

XMLRPC signature
redirect.checkPhone(mac)

Parameter:

  1. mac: MAC address the requesting user wants to check.

Return values:

  1. Result code: True, False
  2. Result text:
    1. Ok, if the requesting user owns the given mac address.
    2. Error:owned_by_other_user if the requested mac is already registered by somebody else, Error:no_such_mac if this mac isn't registered at all or Error:malformed_mac if the given MAC is faulty.

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.checkPhone</methodName>

 <params>

  <param>

   <value><string>000413230c25</string></value>

  </param>

 </params>

</methodCall>

Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.registerPhoneList

A list of MACs can be registered at the redirection service in order to redirect the specified phones to a different setting server.

XMLRPC signature
redirect.registerPhoneList(macList, provisioningUrl)

Parameter:

  1. macList: A list of MAC addresses.
  2. provisioningUrl: The URL the phones to be registered should be redirected to.

Return values:

  1. Result code: True, False
  2. Result text:
    1. Ok, if the whole given list of mac addresses could be successfully registered to the requesting user.
    2. Error:malformed_mac_list, if the given list of mac addresses is NIL or empty.
    3. If only parts of the given list of mac addresses is faulty, those incorrect MAC addresses are returned in pairs together with the specific error message applying to this mac address respectively, like {000413250c24: Error:malformed_url, 000413250c25: Error:malformed_mac,000413250c26: Error:owned_by_other_user}

The following snipplets are showing examples of the handshake of the above described XMLRPC request.

Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.registerPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413250c23</string></value>

    <value><string>000413250c24</string></value>

    <value><string>000413250c25</string></value>

   </data></array></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prv2.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

positive Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

negative Answer of malformed_mac_list:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:malformed_mac_list</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Another Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.registerPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413244321</string></value>

    <value><string>000413270c23</string></value>

    <value><string>000413270c24</string></value>

    <value><string>000413270c25</string></value>

   </data></array></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prv2.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

negative Answer of owned_by_other_user:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><struct>

     <member>

      <name>000413270c24</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

     <member>

      <name>000413270c25</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

     <member>

      <name>000413244321</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

     <member>

      <name>000413270c23</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

    </struct></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.deregisterPhoneList

A list of registered phones (MACs) can be deregistered from the service.

XMLRPC signature
redirect.deregisterPhoneList(macList)

Parameter:

  1. macList: A list of MAC addresses

Return values:

  1. Result code: True, False
  2. Result text:
    1. Ok, if the requesting user owns the list of given mac addresses and the mac addresses could be deregistered successfully.
    2. Error:malformed_mac_list, if the given list of mac addresses is NIL or empty.
    3. If only some of the mac addresses on the list are faulty, the incorrect MAC addresses will be returned in pairs with the applicable error message for each mac address. For example: {000413250c24: Error:malformed_url, 000413250c25: Error:malformed_mac,000413250c26: Error:owned_by_other_user}

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.deregisterPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413250c23</string></value>

    <value><string>000413250c24</string></value>

    <value><string>000413250c25</string></value>

   </data></array></value>

  <param>

 </params>

</methodCall>

positive Answer:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Another Request:
<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.deregisterPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413260c23</string></value>

    <value><string>000413260c24</string></value>

    <value><string>000413260c25</string></value>

   </data></array></value>

  </param>

 </params>

</methodCall>

negative Answer of no_such_mac:
<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><struct>

     <member>

      <name>000413260c23</name>

      <value><string>Error:no_such_mac</string></value>

     </member>

     <member>

      <name>000413260c25</name>

      <value><string>Error:no_such_mac</string></value>

     </member>

     <member>

      <name>000413260c24</name>

      <value><string>Error:no_such_mac</string></value>

     </member>

    </struct></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Redirection CLI

The Redirection CLI is a XMLRPC client based on python.

http://wiki.snom.com/Redirection_CLI

This category currently contains no pages or media.

Personal tools
Interoperability