<<TOC(3)>>

See also:
 * [[ROS/Master_Slave_APIs|Master Slave APIs]]
 * [[ROS/Slave_API|Slave API]]
 * [[ROS/Parameter Server API|Parameter Server API]]

== Using XMLRPC ==

The Master API is implemented via XMLRPC, which has good library support in a variety of languages. For example, in Python:

{{{
import os
import xmlrpclib
caller_id = '/script'
m = xmlrpclib.ServerProxy(os.environ['ROS_MASTER_URI'])
code, msg, val = m.getSystemState(caller_id)
if code == 1:
  pubs, subs, srvs = val
else:
  print "call failed", code, msg
}}}

== API Listing ==

'''Language-specific client APIs as well as tools may define convenience methods that make it unnecessary to call these APIs directly.'''


=== register/unregister methods ===

`registerService(caller_id, service, service_api, caller_api)`
  Register the caller as a provider of the specified service.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `service` (str)
     Fully-qualified name of service 
   `service_api` (str)
     ROSRPC Service URI 
   `caller_api` (str)
     XML-RPC URI of caller node 
  ''Returns'' (int, str, int)
     (code, statusMessage, ignore)

`unregisterService(caller_id, service, service_api)`
  Unregister the caller as a provider of the specified service.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `service` (str)
     Fully-qualified name of service 
   `service_api` (str)
     API URI of service to unregister. Unregistration will only occur if current registration matches.
  ''Returns'' (int, str, int)
     (code, statusMessage, numUnregistered).
     <<BR>>
     Number of unregistrations (either 0 or 1). If this is zero it means that the caller was not registered as a service provider. The call still succeeds as the intended final state is reached.

`registerSubscriber(caller_id, topic, topic_type, caller_api)`
  Subscribe the caller to the specified topic. In addition to receiving a list of current publishers, the subscriber will also receive notifications of new publishers via the publisherUpdate API.        

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `topic` (str)
     Fully-qualified name of topic.
   `topic_type` (str)
     Datatype for topic. Must be a package-resource name, i.e. the .msg name.
   `caller_api` (str)
     API URI of subscriber to register. Will be used for new publisher notifications.
  ''Returns'' (int, str, [str])
     (code, statusMessage, publishers)
     <<BR>>
     Publishers is a list of XMLRPC API URIs for nodes currently publishing the specified topic.

`unregisterSubscriber(caller_id, topic, caller_api)`
  Unregister the caller as a publisher of the topic.
  
  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `topic` (str)
     Fully-qualified name of topic.
   `caller_api` (str)
     API URI of subscriber to unregister. Unregistration will only occur if current registration matches.    
  ''Returns'' (int, str, int)
     (code, statusMessage, numUnsubscribed)
     <<BR>>     
     If numUnsubscribed is zero it means that the caller was not registered as a subscriber. The call still succeeds as the intended final state is reached.

`registerPublisher(caller_id, topic, topic_type, caller_api)`
  Register the caller as a publisher the topic.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `topic` (str)
     Fully-qualified name of topic to register.
   `topic_type` (str)
     Datatype for topic. Must be a package-resource name, i.e. the .msg name.
   `caller_api` (str)
     API URI of publisher to register.

  ''Returns'' (int, str, [str])
    (code, statusMessage, subscriberApis)
    <<BR>>    
    List of current subscribers of topic in the form of XMLRPC URIs.

`unregisterPublisher(caller_id, topic, caller_api)`
  Unregister the caller as a publisher of the topic.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `topic` (str)
     Fully-qualified name of topic to unregister.
   `caller_api` (str)
     API URI of publisher to unregister. Unregistration will only occur if current registration matches.

  ''Returns'' (int, str, int)
    (code, statusMessage, numUnregistered)
    <<BR>>
    If numUnregistered is zero it means that the caller was not registered as a publisher. The call still succeeds as the intended final state is reached.

=== Name service and system state ===

`lookupNode(caller_id, node_name)`
  Get the XML-RPC URI of the node with the associated name/caller_id.  This API is for looking information about publishers and subscribers. Use lookupService instead to lookup ROS-RPC URIs.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `node` (str)
     Name of node to lookup

  ''Returns'' (int, str, str)
    (code, statusMessage, URI)
        
`getPublishedTopics(caller_id, subgraph)`
  Get list of topics that can be subscribed to. This does not return topics that have no publishers. See getSystemState() to get more comprehensive list.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `subgraph` (str)
     Restrict topic names to match within the specified subgraph. Subgraph namespace is resolved relative to the caller's namespace. Use empty string to specify all names.

  ''Returns'' (int, str, [[str, str],])
    (code, statusMessage, [ [topic1, type1]...[topicN, typeN] ])


`getTopicTypes(caller_id)`
  Retrieve list topic names and their types.
  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
  ''Returns'' (int, str, [ [str,str] ])
     (code, statusMessage, topicTypes)
     <<BR>>
     topicTypes is a list of [topicName, topicType] pairs.
    
`getSystemState(caller_id)` 
  Retrieve list representation of system state (i.e. publishers, subscribers, and services).

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
  ''Returns'' (int, str, [ [str,[str] ], [str,[str] ], [str,[str] ] ])
    (code, statusMessage, systemState)
    <<BR>>    
    System state is in list representation {{{
[publishers, subscribers, services]
}}}

    publishers is of the form{{{
[ [topic1, [topic1Publisher1...topic1PublisherN]] ... ]
}}}

    subscribers is of the form{{{
[ [topic1, [topic1Subscriber1...topic1SubscriberN]] ... ]
}}}

    services is of the form{{{
[ [service1, [service1Provider1...service1ProviderN]] ... ]
}}}

`getUri(caller_id)` 
  Get the URI of the master.
  
  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
  ''Returns'' (int, str, str)
     (code, statusMessage, masterURI)

`lookupService(caller_id, service)`
  Lookup all provider of a particular service.

  <<BR>>
  ''Parameters''
   `caller_id` (str)
     ROS caller ID
   `service` (str)
     Fully-qualified name of service 
  ''Returns'' (int, str, str)
     (code, statusMessage, serviceUrl)
     <<BR>>
     service URL is provides address and port of the service.  Fails if there is no provider.