客户端

客户端关于推送的方法只有两个，它们分别是：

Subscribe 方法

  1. Subscribe(name string, id string, settings *InvokeSettings, callback interface{}) (err error)

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

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

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

参数 id 是客户端的唯一编号，如果设置为 "" 的话，客户端会使用自动编号机制，如果该自动编号未初始化，会自动调用一个名字为 # 的服务器端远程方法，之所以使用这个特殊的名字是为了防止跟用户发布的普通方法发生冲突。Hprose 2.0 服务器已经自动实现了该方法，但是用户也可以用自己的实现来替换它，它现在的默认实现是一个 UUID 字符串。当用户指定了 id 参数时，客户端会将它作为该 name 对应方法的参数值传给服务器端，但不会修改客户端的自动编号。如果自动编号获取失败，该方法将返回错误。

参数 callback 是用来处理推送消息的回调函数，如果该参数不是函数类型，该方法将返回错误。

参数 settings 是订阅选项，但与 Invoke 调用不同，Subscribe 方法仅有以下几个选项可以设置：

  • Timeout 字段
  • Failswitch 字段
  • JSONCompatible 字段
  • SetUserData 方法
    Timeout 字段表示等待推送消息的超时时间，可以省略，省略时表示与客户端的 Timeout 默认设置相同。超时之后并不会产生异常，而是重新请求推送。因为服务器端推送本身也有超时机制，因此，Timeout 所设置的超时时间最好长于服务器端的超时时间，这样可以避免产生多余的通讯。如果用户要在服务器端自己实现推送方法，应当注意处理好同一个客户端对同一个推送方法可能会进行重复调用的问题。如果使用 Hprose 2.0 提供的推送 API，则不需要关心这一点。

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

JSONCompatible 字段表示如果回调方法中的参数类型为 interface{}，而推送的信息中又包含 map 数据，当该字段设置为 true 时，map 将被反序列化为 map[string]interface{} 类型。默认是反序列化为 map[interface{}]interface{} 类型。

SetUserData 方法用于为中间件或过滤器的 context 参数设置一些初始化的用户数据，通常在推送中很少用的。

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

Unsubscribe 方法

  1. Unsubscribe(name string, id ...string)

该方法用于取消订阅推送主题。

如果 id 参数未指定，而且如果客户端自动编号未初始化，将取消该主题上的所有订阅，否则只取消该主题上与指定 id 或者自动编号对应的订阅。

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

AutoID 方法

  1. AutoID() (string, error)

该方法返回当前客户端在进行推送订阅时自动获取的唯一编号。如果自动编号没有初始化，则自动调用远程服务初始化。

ID 方法

  1. ID() string

与 AutoID 类似，只是当自动编号没有初始化时，该方法返回空字符串。

IsSubscribed 方法

  1. IsSubscribed(name string) bool

当 name 所对应的主题已被订阅时，返回 true，否则返回 false。

SubscribedList 方法

  1. SubscribedList() []string

返回已被订阅的主题的列表。返回的 []string 中的元素为已订阅的主题名称。