Primus 0.0.8

Primus 0.0.8

测试已测试
语言语言 Obj-CObjective C
许可证 MIT
发布最后发布2015年8月

Nuno Sousa 维护。



 
依赖
libextobjc/EXTScope>= 0
GCDTimer>= 0
Reachability>= 0
Emitter>= 0
 

Primus 0.0.8

  • Nuno Sousa

Primus-Objc

Primus-Objc 是 Primus JavaScript 客户端层的实现。

该库通过 SpectaExpectaOCMockito 进行了完全的单元测试。

Build Status

当前支持的实时框架

安装

pod 'Primus'

pod 'SocketRocket'
# or pod 'socket.IO'

目录

入门

以下是一个快速示例,说明如何建立与 Primus 服务器连接并监听我们发出的各种事件。

由于我们没有指定转换器,Primus 将连接到 /spec 端点 并尝试确定适当的实时框架。

#import <Primus/Primus.h>

- (void)start
{
    NSURL *url = [NSURL URLWithString:@"https://:9090/primus"];

    Primus *primus = [[Primus alloc] initWithURL:url];

    [primus on:@"reconnect" listener:^(PrimusReconnectOptions *options) {
        NSLog(@"[reconnect] - We are scheduling a new reconnect attempt");
    }];

    [primus on:@"online" listener:^{
        NSLog(@"[network] - We have regained control over our internet connection.");
    }];

    [primus on:@"offline" listener:^{
        NSLog(@"[network] - We lost our internet connection.");
    }];

    [primus on:@"open" listener:^{
        NSLog(@"[open] - The connection has been established.");
    }];

    [primus on:@"error" listener:^(NSError *error) {
        NSLog(@"[error] - Error: %@", error);
    }];

    [primus on:@"data" listener:^(NSDictionary *data, id raw) {
        NSLog(@"[data] - Received data: %@", data);
    }];

    [primus on:@"end" listener:^{
        NSLog(@"[end] - The connection has ended.");
    }];

    [primus on:@"close" listener:^{
        NSLog(@"[close] - We've lost the connection to the server.");
    }];
}

Primus 也可以使用 NSURLRequest 类初始化,这样您可以添加自己的 HTTP 标头,例如

    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://:9090/primus"]];

    [request setValue:@"Bearer <your-oauth-token-here>" forHTTPHeaderField:@"Authorization"];

    Primus *primus = [[Primus alloc] initWithURLRequest:request];

还可以通过传入 PrimusConnectOptions 对象的实例来进行进一步的定制

    NSURL *url = [NSURL URLWithString:@"https://:9090/primus"];

    PrimusConnectOptions *options = [[PrimusConnectOptions alloc] init];

    options.transformerClass = SocketRocketClient.class;
    options.strategy = @[@(kPrimusReconnectionStrategyTimeout)];
    options.timeout = 200;
    options.manual = YES;

    Primus *primus = [[Primus alloc] initWithURL:url options:options];

连接

当您使用默认选项初始化 Primus 实例时,它将自动连接。这是为了与原始 Primus 库保持兼容。

但是,如果您想手动连接,您必须传递自定义 PrimusConnectOptions 给初始化器并调用 open 方法

    NSURL *url = [NSURL URLWithString:@"https://:9090/primus"];

    PrimusConnectOptions *options = [[PrimusConnectOptions alloc] init];

    options.manual = YES;

    Primus *primus = [[Primus alloc] initWithURL:url options:options];

    // Calling 'open' will start the connection
    [primus open];

在连接成功建立时,将发出 open 事件。

授权

如果您使用了服务器端的 授权钩子,如果授权失败,Primus 将发出一个 error 事件。

然后您可以根据您的授权逻辑检索错误代码。

广播

广播允许您将消息写入服务器。您目前可以广播 NSDictionaryNSStringNSData 的实例。

[primus write:@{
    @"my-data": @(123)
}];

[primus write:@"example-data"];

断开连接

您可以通过调用end方法轻松地与服务器断开连接。如果Primus成功断开连接,它也会发射一个end事件。

[primus end];

事件

Primus基于EventEmitter模式,使用Emitter库构建。以下是Primus发射事件的概述。

事件 使用 位置 描述
reconnecting 公开 客户端 我们正在安排一个重连。
reconnect 公开 客户端 即将进行重连尝试。
outgoing::open 私有 客户端 转换器应该连接。
incoming::open 私有 客户端 转换器已连接。
open 公开 客户端 连接已打开。
incoming::error 私有 客户端 转换器收到错误。
error 公开 客户端 发生了错误。
incoming::data 私有 客户端 转换器收到数据。
outgoing::data 私有 客户端 转换器应该写入数据。
data 公开 客户端 我们收到了数据。
incoming::end 私有 客户端 转换器关闭了连接。
outgoing::end 私有 客户端 转换器应该关闭连接。
end 公开 客户端 Primus已结束。
close 公开 客户端 底层连接已关闭,我们可能会重试。
initialised 公开 客户端 服务器已初始化。
incoming::pong 私有 客户端 我们收到一个pong消息。
outgoing::ping 私有 客户端 我们正在发送一个ping消息。
online 公开 客户端 我们恢复了网络连接。
offline 公开 客户端 我们失去了互联网连接。

心跳和延迟

Primus心跳机制已按原始框架中的描述实现。

后台支持

对于iOS,Primus支持在后台保持连接。此选项可在PrimusConnectOptions对象中启用。如果您的应用程序配置了Apple的文档中描述的VOIP UIBackgroundMode,则自动设置为true

为了保持连接,我们需要发送一个primus::ping::<timestamp>消息,这意味着我们需要偶尔使用一些CPU时间。Apple允许的后台任务的最大间隔是10分钟,这意味着您必须将服务器端Primus至少配置为10分钟的超时时间。

以下是在JavaScript中配置服务器的一个示例:

var primus = new Primus(server, {
    transformer: 'websockets',
    timeout: 630000      // 10 minutes and 30 secs
});

插件

Primus JavaScript框架允许服务器端和客户端使用插件。

Primus-Objc支持客户端插件以及消息转换器。

转换和拦截消息

您可以通过注册一个转换块来拦截和转换incomingoutgoing数据。

    [self transform:@"incoming" fn:^BOOL(NSMutableDictionary *data) {
        data[@"foo"] = @"bar";

        return YES;
    }];

您还可以防止data事件被发射,通过在转换块中返回NO。这将会有效地丢弃消息。

社区插件

这些是由我们的社区创建的插件。如果您创建了一个模块,请提交一个pull请求并将其添加到这一节。

primus-emitter-objc

    一个使Primus具有发射能力的模块。

测试

大部分功能都有测试覆盖。对于实时客户端,我们启动了一个小型节点服务器和相应的实时框架,并对其进行测试。

在运行测试之前,请运行

pod install
npm install

然后您可以使用XCode打开项目,选择产品→测试(⌘U)。

许可证

MIT