Snom Service Hub

Content

Page tree


Protocol description

The interface between client and server is built as XML-RPC 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.

The XML-RPC interface is secured and encrypted via TLS, user authentication is done via HTTP basic authentication mechanism.


Creating an XML-RPC client

  • The URL for XML-RPC requests is https://secure-provisioning.snom.com:8083/xmlrpc/ the trailing slash ("/") is mandatory.
  • The header Content-type: text/xml is mandatory
  • All XML-RPC methods must be prefixed by the redirection namespace (eg. redirect.registerPhone )


Available methods


Method XML signatureDescriptionParametersReturn

redirect.registerPhone(mac, provisioningUrl)

Register a device mac address redirection to a specific URL
  • mac: the device mac address
  • provisioningUrl: the redirection URL

Return code:

  • True (in case of success)
  • False (in case of failure)

Return text:

  • Ok if the given mac address could be registered successfully to the mac addresses of the requesting user.
  • Error:owned_by_other_user if the requested mac is already registered to somebody else
  • Error:malformed_url if the given provisioningUrl is fault
  • Error:malformed_mac if the given MAC is faulty

redirect.deregisterPhone(mac)

Deregister a specific mac from the servi e
  • mac: the device mac address

Return code:

  • True (in case of success)
  • False (in case of failure)

Return text:

  • Ok if the given mac address could be registered successfully to the mac addresses of the requesting user.
  • Error:owned_by_other_user if the requested mac is already registered to somebody else
  • Error:malformed_mac if the given MAC is faulty
redirect.getPhoneRedirection(mac)Retrieve the redirection URL of a specific mac
  • mac: the device mac address

Return code:

  • True (in case of success)
  • False (in case of failure)

Return text:

  • Company name, Redirection URL if the given mac address is redirected to an URL
  • Error:owned_by_other_user if the requested mac is already registered to somebody else
  • Error:malformed_mac if the given MAC is faulty

redirect.listPhones(deviceType, provisioningUrl=None)

List all the registered mac address of a given type or optionally redirected to a particular URL
  • deviceType: the device model
  • provisioningUrl: the redirection target (optional)

Returned data:

  • An array of mac addresses if the system found one or more devices matching the type and optionally the URL
  • An empty array of mac addresses if the system cannot find any device
redirect.checkPhone(mac)

Checks if a device is registered to the requesting user.

  • mac: the device mac address

Return code:

  • True (in case of success)
  • False (in case of failure)

Return text:

  • Ok if the requesting user own the given mac address
  • Error:owned_by_other_user if the requested mac is already registered to somebody else
  • Error:malformed_mac if the given MAC is faulty
  • Error:no_such_mac if the the mac isn't registered at all

redirect.registerPhoneList(macList, provisioningUrl)

Register a list of MACs at the redirection service in order to redirect the specified phones to a different setting server.

  • macList: a list of mac addresses to be redirected
  • provisioningUrl: the redirection URL

Return code:

  • True (in case of success)
  • False (in case of failure)

Return text:

  • Ok if the given mac address could be registered successfully to the mac addresses of the requesting user.
  • Error:malformed_mac_list if the given list of mac addresses is NIL or empty.

  • 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}

redirect.deregisterPhoneList(macList)

Deregister a list of MACs
  • macList: a list of mac addresses to be deregistered

Return code:

  • True (in case of success)
  • False (in case of failure)

Return text:

  • Ok if the given mac address could be registered successfully to the mac addresses of the requesting user.
  • Error:malformed_mac_list if the given list of mac addresses is NIL or empty.

  • 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}

XML-RPC exchange snippets

The following code snippets are examples using the curl command as a tool to send the XML-RPC request.

Registering a device

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.registerPhone</methodName>
 <params>
  <param>
   <value><string>000413610FF5</string></value>
  </param>
  <param>
   <value><string>http://provisioning.myserver.com/snom?mac={mac}</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><boolean>1</boolean></value>
      <value><string>Ok</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodResponse>

Deregistering a device

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.deregisterPhone</methodName>
 <params>
  <param>
   <value><string>000413610FF5</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><boolean>1</boolean></value>
      <value><string>Ok</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodResponse>

Get a device redirection

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.getPhoneRedirection</methodName>
 <params>
  <param>
   <value><string>000413610FF5</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><string>Snom Technology GmbH</string></value>
      <value><string>http://provisioning.myserver.com/snom?mac={mac}</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodResponse>

List registered phones by model

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.listPhones</methodName>
 <params>
  <param>
   <value><string>snomM700</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><string>000413610ff5</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodResponse>

List registered phones by model and URL

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.listPhones</methodName>
 <params>
  <param>
   <value><string>snomM700</string></value>
  </param>
  <param>
   <value><string>http://provisioning.myserver.com/snom?mac={mac}</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><string>000413610ff5</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodResponse>

Check a device

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.checkPhone</methodName>
 <params>
  <param>
   <value><string>000413610FF5</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><boolean>1</boolean></value>
      <value><string>Ok</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodResponse>

Register a list of devices

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.registerPhoneList</methodName>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><string>000413610FF5</string></value>
      <value><string>000413610FF6</string></value>
      <value><string>000413610FF7</string></value>
     </data>
    </array>
   </value>
  </param>
  <param>
   <value><string>http://provisioning.myserver.com/snom?mac={mac}</string></value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value><array><data>
    <value><boolean>1</boolean></value>
    <value><string>Ok</string></value>
   </data></array></value>
  </param>
 </params>
</methodResponse>

Deregister a list of devices

curl https://secure-provisioning.snom.com:8083/xmlrpc/ \
	-X POST \
	-H "Content-type: text/xml" \
	--user $USERNAME:$PASSWORD \
	--data \
'<?xml version="1.0"?>
<methodCall>
 <methodName>redirect.deregisterPhoneList</methodName>
 <params>
  <param>
   <value>
    <array>
     <data>
      <value><string>000413610FF5</string></value>
      <value><string>000413610FF6</string></value>
      <value><string>000413610FF7</string></value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodCall>'

<?xml version='1.0' encoding='utf-8'?>
<methodResponse>
 <params>
  <param>
   <value><array><data>
    <value><boolean>1</boolean></value>
    <value><string>Ok</string></value>
   </data></array></value>
  </param>
 </params>
</methodResponse>

Further Information


Related articles