测试已测试 | ✓ |
语言语言 | Obj-CObjective C |
许可证 | MIT |
发布最后发布 | 2015年8月 |
由 Nuno Sousa 维护。
依赖 | |
libextobjc/EXTScope | >= 0 |
GCDTimer | >= 0 |
Reachability | >= 0 |
Emitter | >= 0 |
Primus-Objc 是 Primus JavaScript 客户端层的实现。
该库通过 Specta,Expecta 和 OCMockito 进行了完全的单元测试。
当前支持的实时框架
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
事件。
然后您可以根据您的授权逻辑检索错误代码。
广播允许您将消息写入服务器。您目前可以广播 NSDictionary
,NSString
或 NSData
的实例。
[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支持客户端插件以及消息转换器。
您可以通过注册一个转换块来拦截和转换incoming
或outgoing
数据。
[self transform:@"incoming" fn:^BOOL(NSMutableDictionary *data) {
data[@"foo"] = @"bar";
return YES;
}];
您还可以防止data
事件被发射,通过在转换块中返回NO
。这将会有效地丢弃消息。
这些是由我们的社区创建的插件。如果您创建了一个模块,请提交一个pull请求并将其添加到这一节。
一个使Primus具有发射能力的模块。
大部分功能都有测试覆盖。对于实时客户端,我们启动了一个小型节点服务器和相应的实时框架,并对其进行测试。
在运行测试之前,请运行
pod install
npm install
然后您可以使用XCode打开项目,选择产品→测试(⌘U)。
MIT