mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-06-21 19:04:49 +02:00
Initial check-in
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2149 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Gaston Dombiak
gdombiak
parent
62c74384c8
commit
ad7c383943
193
documentation/extensions/disco.html
Normal file
193
documentation/extensions/disco.html
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>Service Discovery</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css" />
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="header">Service Discovery</div><p>
|
||||
|
||||
The service discovery extension allows to discover items and information about XMPP
|
||||
entities. Follow these links to learn how to use this extension.
|
||||
|
||||
<ul>
|
||||
<li><a href="#discoregister">Manage XMPP entity features</a></li>
|
||||
<li><a href="#discoitems">Discover items associated with an XMPP entity</a></li>
|
||||
<li><a href="#discoinfo">Discover information about an XMPP entity</a></li>
|
||||
<li><a href="#discopublish">Publish publicly available items</a></li>
|
||||
</ul>
|
||||
<b>JEP related:</b> <a href="http://www.jabber.org/jeps/jep-0030.html">JEP-30</a>
|
||||
|
||||
<hr>
|
||||
|
||||
<div class="subheader"><a name="discoregister">Manage XMPP entity features</a></div><p>
|
||||
|
||||
<b>Description</b><p>
|
||||
|
||||
Any XMPP entity may receive a discovery request and must answer with its associated items or
|
||||
information. Therefore, your Smack client may receive a discovery request that must respond
|
||||
to (i.e., if your client supports XHTML-IM). This extension automatically responds to a
|
||||
discovery request with the information that you previously configured.</p>
|
||||
|
||||
<p>
|
||||
Note: This version only allows you to configure supported features by the client. In future
|
||||
version we will add the ability to configure associated items within the Smack client.</p>
|
||||
|
||||
<b>Usage</b><p>
|
||||
|
||||
In order to configure the supported features by your client you should first obtain the
|
||||
ServiceDiscoveryManager associated with your XMPPConnection. To get your ServiceDiscoveryManager
|
||||
send <b>getInstanceFor(connection)</b> to the class <i><b>ServiceDiscoveryManager</b></i> where
|
||||
connection is your XMPPConnection.<br></p>
|
||||
|
||||
<p>Once you have your ServiceDiscoveryManager you will be able to manage the supported features. To
|
||||
register a new feature send <b>addFeature(feature)</b> to your <i><b>ServiceDiscoveryManager</i></b>
|
||||
where feature is a String that represents the supported feature. To remove a supported feature send
|
||||
<b>removeFeature(feature)</b> to your <i><b>ServiceDiscoveryManager</i></b> where feature is a
|
||||
String that represents the feature to remove.</p>
|
||||
|
||||
<b>Examples</b><p>
|
||||
|
||||
In this example we can see how to add and remove supported features: <br>
|
||||
<blockquote>
|
||||
<pre> <font color="#3f7f5f">// Obtain the ServiceDiscoveryManager associated with my XMPPConnection</font>
|
||||
ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
|
||||
|
||||
<font color="#3f7f5f">// Register that a new feature is supported by this XMPP entity</font>
|
||||
discoManager.addFeature(namespace1);
|
||||
|
||||
<font color="#3f7f5f">// Remove the specified feature from the supported features by this XMPP entity</font>
|
||||
discoManager.removeFeature(namespace2);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
|
||||
<div class="subheader"><a name="discoitems">Discover items associated with an XMPP entity</a></div><p>
|
||||
|
||||
<b>Description</b><p>
|
||||
|
||||
In order to obtain information about a specific item you have to first discover the items available
|
||||
in an XMPP entity.</p>
|
||||
|
||||
<b>Usage</b><p>
|
||||
|
||||
<p>Once you have your ServiceDiscoveryManager you will be able to discover items associated with
|
||||
an XMPP entity. To discover the items of a given XMPP entity send <b>discoverItems(entityID)</b>
|
||||
to your <i><b>ServiceDiscoveryManager</i></b> where entityID is the ID of the entity. The message
|
||||
<b>discoverItems(entityID)</b> will answer an instance of <i><b>DiscoverItems</i></b> that contains
|
||||
the discovered items.</p>
|
||||
|
||||
<b>Examples</b><p>
|
||||
|
||||
In this example we can see how to discover the items associated with an online catalog service: <br>
|
||||
<blockquote>
|
||||
<pre> <font color="#3f7f5f">// Obtain the ServiceDiscoveryManager associated with my XMPPConnection</font>
|
||||
ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
|
||||
|
||||
<font color="#3f7f5f">// Get the items of a given XMPP entity</font>
|
||||
<font color="#3f7f5f">// This example gets the items associated with online catalog service</font>
|
||||
DiscoverItems discoItems = discoManager.discoverItems("plays.shakespeare.lit");
|
||||
|
||||
<font color="#3f7f5f">// Get the discovered items of the queried XMPP entity</font>
|
||||
Iterator it = discoItems.getItems();
|
||||
<font color="#3f7f5f">// Display the items of the remote XMPP entity</font>
|
||||
while (it.hasNext()) {
|
||||
DiscoverItems.Item item = (DiscoverItems.Item) it.next();
|
||||
System.out.println(item.getEntityID());
|
||||
System.out.println(item.getNode());
|
||||
System.out.println(item.getName());
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
|
||||
<div class="subheader"><a name="discoinfo">Discover information about an XMPP entity</a></div><p>
|
||||
|
||||
<b>Description</b><p>
|
||||
|
||||
Once you have discovered the entity ID and name of an item, you may want to find out more
|
||||
about the item. The information desired generally is of two kinds: 1) The item's identity
|
||||
and 2) The features offered by the item.</p>
|
||||
|
||||
<p>This information helps you determine what actions are possible with regard to this
|
||||
item (registration, search, join, etc.) as well as specific feature types of interest, if
|
||||
any (e.g., for the purpose of feature negotiation).</p>
|
||||
|
||||
<b>Usage</b><p>
|
||||
|
||||
<p>Once you have your ServiceDiscoveryManager you will be able to discover information associated with
|
||||
an XMPP entity. To discover the information of a given XMPP entity send <b>discoverInfo(entityID)</b>
|
||||
to your <i><b>ServiceDiscoveryManager</i></b> where entityID is the ID of the entity. The message
|
||||
<b>discoverInfo(entityID)</b> will answer an instance of <i><b>DiscoverInfo</i></b> that contains
|
||||
the discovered information.</p>
|
||||
|
||||
<b>Examples</b><p>
|
||||
|
||||
In this example we can see how to discover the information of a conference room: <br>
|
||||
<blockquote>
|
||||
<pre> <font color="#3f7f5f">// Obtain the ServiceDiscoveryManager associated with my XMPPConnection</font>
|
||||
ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
|
||||
|
||||
<font color="#3f7f5f">// Get the information of a given XMPP entity</font>
|
||||
<font color="#3f7f5f">// This example gets the information of a conference room</font>
|
||||
DiscoverInfo discoInfo = discoManager.discoverInfo("balconyscene@plays.shakespeare.lit");
|
||||
|
||||
<font color="#3f7f5f">// Get the discovered identities of the remote XMPP entity</font>
|
||||
Iterator it = discoInfo.getIdentities();
|
||||
<font color="#3f7f5f">// Display the identities of the remote XMPP entity</font>
|
||||
while (it.hasNext()) {
|
||||
DiscoverInfo.Identity identity = (DiscoverInfo.Identity) it.next();
|
||||
System.out.println(identity.getName());
|
||||
System.out.println(identity.getType());
|
||||
System.out.println(identity.getCategory());
|
||||
}
|
||||
|
||||
<font color="#3f7f5f">// Check if room is password protected</font>
|
||||
discoInfo.containsFeature("muc_passwordprotected");
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
|
||||
<div class="subheader"><a name="discopublish">Publish publicly available items</a></div><p>
|
||||
|
||||
<b>Description</b><p>
|
||||
|
||||
Publish your entity items to some kind of persistent storage. This enables other entities to query
|
||||
that entity using the disco#items namespace and receive a result even when the entity being queried
|
||||
is not online (or available).</p>
|
||||
|
||||
<b>Usage</b><p>
|
||||
|
||||
<p>Once you have your ServiceDiscoveryManager you will be able to publish items to some kind of
|
||||
persistent storage. To publish the items of a given XMPP entity you have to first create an instance
|
||||
of <i><b>DiscoverItems</i></b> and configure it with the items to publish. Then you will have to
|
||||
send <b>publishItems(String entityID, DiscoverItems discoverItems)</b> to your <i><b>ServiceDiscoveryManager</i></b>
|
||||
where entityID is the address of the XMPP entity that will persist the items and discoverItems contains the items
|
||||
to publish.</p>
|
||||
|
||||
<b>Examples</b><p>
|
||||
|
||||
In this example we can see how to publish new items: <br>
|
||||
<blockquote>
|
||||
<pre> <font color="#3f7f5f">// Obtain the ServiceDiscoveryManager associated with my XMPPConnection</font>
|
||||
ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
|
||||
|
||||
<font color="#3f7f5f">// Create a DiscoverItems with the items to publish</font>
|
||||
DiscoverItems itemsToPublish = new DiscoverItems();
|
||||
DiscoverItems.Item itemToPublish = new DiscoverItems.Item("pubsub.shakespeare.lit");
|
||||
itemToPublish.setName("Avatar");
|
||||
itemToPublish.setNode("romeo/avatar");
|
||||
itemToPublish.setAction(DiscoverItems.Item.UPDATE_ACTION);
|
||||
itemsToPublish.addItem(itemToPublish);
|
||||
|
||||
<font color="#3f7f5f">// Publish the new items by sending them to the server</font>
|
||||
discoManager.publishItems("host", itemsToPublish);
|
||||
</pre>
|
||||
</blockquote>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
Loading…
Reference in a new issue