推送服务

subscribe 方法

client.subscribe(topic, callback[, timeout[, failswitch]]);
client.subscribe(topic, id, callback[, timeout[, failswitch]]);

subscribe 方法的用处是订阅服务器端的推送服务。该方法有两种方式，一种是自动获取设置客户端 id，另一种是手动设置客户端 id。

参数 topic 是订阅的主题名，它实际上也是一个服务器端的方法，该方法与普通方法的区别是，它只有一个参数 id，该参数表示客户端的唯一编号，该方法的返回值即推送信息，当返回值为 null 或者抛出异常时，客户端会忽略并再次调用该 topic 方法。当该方法返回推送消息时，callback 回调函数会执行，并同时再次调用该 topic 方法。因此当没有推送消息时，该方法不应该立即返回值，而应该挂起等待，直到超时或者有推送消息时再返回结果。

当然，对于开发者来说，自己实现一个完善的推送方法还是有一定难度的。因此，hprose 2.0 的服务器端已经提供了一整套的专门用于推送的 API，通过这些 API，可以方便的自动实现用于推送的服务方法。在后面介绍服务器端时，我们再介绍这部分内容。

参数 id 是客户端的唯一编号，如果省略的话，客户端会自动通过 client 的 id 属性来获取，如果该属性未初始化，会自动调用一个名字为 # 的服务器端远程方法，之所以使用这个特殊的名字是为了防止跟用户发布的普通方法发生冲突。hprose 2.0 服务器已经自动实现了该方法，但是用户也可以用自己的实现来替换它，它的默认实现是一个整数自增计数器。当用户指定了 id 参数时，客户端会将它作为该 topic 方法的参数值传给服务器端，但不会修改客户端的 id 属性值。

参数 callback 是用来处理推送消息的回调函数，该参数不能省略。

参数 timeout 是等待推送消息的超时时间，单位是毫秒（ms），可以省略，默认值与 timeout 属性值相同。超时之后并不会产生异常，而是重新发起对 topic 方法的调用。因此，如果用户要在服务器端自己实现推送方法，应当注意处理好同一个客户端对同一个推送方法可能会进行重复调用的问题。如果使用 hprose 2.0 提供的推送 API，则不需要关心这一点。

参数 failswitch 表示当客户端与服务器端通讯中发生网络故障，是否自动切换服务器。默认值是 false，表示不切换。

对于同一个推送主题，subscribe 方法允许被多次调用，这样可以对同一个推送主题指定多个不同的回调方法。但通常没有必要也不推荐这样做。

unsubscribe 方法

client.unsubscribe(topic)
client.unsubscribe(topic, callback)
client.unsubscribe(topic, id)
client.unsubscribe(topic, id, callback)

该方法用于取消订阅推送主题。当调用该方法时，带有 callback 参数，将只取消对该 callback 方法的回调，除非这是该主题上最后一个 callback，否则对该主题远程方法的调用并不会中断。当所有的 callback 都被取消之后，或者当调用该方法时，没有指定 callback 参数时，将会中断对该主题远程方法的循环调用。

如果 id 参数若未指定，那么当客户端 id 属性有值时，将只取消对该 id 属性值对应的推送主题的订阅。当客户端 id 属性未初始化时，将会取消该主题上所有的订阅。

通常来说，当你调用 subscribe 方法时如果指定了 id 参数，那么当调用 unsubscribe 方法时你也应该指定相同的 id 参数。当你调用 subscribe 方法时没有指定 id 参数，那么当调用 unsubscribe 方法时你也不需要指定 id 参数。

isSubscribed 方法

client.isSubscribed(topic);

当 topic 已被订阅时，返回 true，否则返回 false。

subscribedList 方法

client.subscribedList();

返回已被订阅的主题的列表，返回值是一个字符串数组。数组元素为已订阅的主题名称。