149 lines
4.8 KiB
Markdown
149 lines
4.8 KiB
Markdown
Socket.IO-Client-Swift
|
|
======================
|
|
|
|
Socket.IO-client for Swift. Supports ws/wss/polling connections and binary. For socket.io 1.0+ and Swift 1.1.
|
|
|
|
For Swift 1.2 use the 1.2 branch.
|
|
|
|
Installation
|
|
============
|
|
|
|
Manually (iOS 7+)
|
|
-----------------
|
|
1. Copy the SwiftIO folder into your Xcode project!
|
|
|
|
CocoaPods 0.36.0 or later (iOS 8+)
|
|
------------------
|
|
Create `Podfile` and add `pod 'Socket.IO-Client-Swift'`:
|
|
|
|
```ruby
|
|
source 'https://github.com/CocoaPods/Specs.git'
|
|
platform :ios, '8.0'
|
|
use_frameworks!
|
|
|
|
pod 'Socket.IO-Client-Swift', '~> 1.3.2' # Or latest version
|
|
```
|
|
|
|
Install pods:
|
|
|
|
```
|
|
$ pod install
|
|
```
|
|
|
|
Import in your swift file:
|
|
|
|
```swift
|
|
import Socket_IO_Client_Swift
|
|
```
|
|
|
|
API
|
|
===
|
|
Constructors
|
|
-----------
|
|
`init(socketURL: String, opts:NSDictionary? = nil)` - Constructs a new client for the given URL. opts can be omitted (will use default values. See example)
|
|
|
|
`convenience init(socketURL: String, options:NSDictionary?)` - Same as above, but meant for Objective-C. See Objective-C Example.
|
|
Methods
|
|
-------
|
|
1. `socket.on(name:String, callback:((data:NSArray?, ack:AckEmitter?) -> Void))` - Adds a handler for an event. Items are passed by an array. `ack` can be used to send an ack when one is requested. See example.
|
|
2. `socket.onAny(callback:((event:String, items:AnyObject?)) -> Void)` - Adds a handler for all events. It will be called on any received event.
|
|
3. `socket.emit(event:String, _ items:AnyObject...)` - Sends a message. Can send multiple items.
|
|
4. `socket.emitObjc(event:String, withItems items:[AnyObject])` - `emit` for Objective-C
|
|
5. `socket.emitWithAck(event:String, _ items:AnyObject...) -> SocketAckHandler` - Sends a message that requests an acknowledgement from the server. Returns a SocketAckHandler which you can use to add an onAck handler. See example.
|
|
6. `socket.emitWithAckObjc(event:String, withItems items:[AnyObject]) -> SocketAckHandler` - `emitWithAck` for Objective-C.
|
|
7. `socket.connect()` - Establishes a connection to the server. A "connect" event is fired upon successful connection.
|
|
8. `socket.connectWithParams(params:[String: AnyObject])` - Establishes a connection to the server passing the specified params. A "connect" event is fired upon successful connection.
|
|
9. `socket.close(#fast:Bool)` - Closes the socket. Once a socket is closed it should not be reopened. Pass true to fast if you're closing from a background task.
|
|
|
|
Events
|
|
------
|
|
1. `connect` - Emitted when on a successful connection.
|
|
2. `disconnect` - Emitted when the connection is closed.
|
|
3. `error` - Emitted if the websocket encounters an error.
|
|
4. `reconnect` - Emitted when the connection is starting to reconnect.
|
|
5. `reconnectAttempt` - Emitted when attempting to reconnect.
|
|
|
|
Example
|
|
=======
|
|
```swift
|
|
// opts can be omitted, will use default values
|
|
let socket = SocketIOClient(socketURL: "https://localhost:8080", opts: [
|
|
"reconnects": true, // Default is true
|
|
"reconnectAttempts": 5, // Default is -1 (infinite tries)
|
|
"reconnectWait": 5, // Default is 10
|
|
"nsp": "swift", // connects to the specified namespace. Default is /
|
|
"forcePolling": true, // if true, the socket will only use XHR polling, Default is false (polling/WebSockets)
|
|
"cookies": nil // An array of NSHTTPCookies. Passed during handshake. Default is nil
|
|
])
|
|
|
|
// Called on every event
|
|
socket.onAny {println("got event: \($0.event) with items \($0.items)")}
|
|
|
|
// Socket Events
|
|
socket.on("connect") {data, ack in
|
|
println("socket connected")
|
|
|
|
// Sending messages
|
|
socket.emit("testEcho")
|
|
|
|
socket.emit("testObject", [
|
|
"data": true
|
|
])
|
|
|
|
// Sending multiple items per message
|
|
socket.emit("multTest", [1], 1.4, 1, "true",
|
|
true, ["test": "foo"], "bar")
|
|
}
|
|
|
|
// Requesting acks, and responding to acks
|
|
socket.on("ackEvent") {data, ack in
|
|
if let str = data?[0] as? String {
|
|
println("Got ackEvent")
|
|
}
|
|
|
|
// data is an array
|
|
if let int = data?[1] as? Int {
|
|
println("Got int")
|
|
}
|
|
|
|
// You can specify a custom timeout interval. 0 means no timeout.
|
|
socket.emitWithAck("ackTest", "test").onAck(0) {data in
|
|
println(data?[0])
|
|
}
|
|
|
|
ack?("Got your event", "dude")
|
|
}
|
|
|
|
socket.on("jsonTest") {data, ack in
|
|
if let json = data?[0] as? NSDictionary {
|
|
println(json["test"]!) // foo bar
|
|
}
|
|
}
|
|
|
|
// Connecting
|
|
socket.connect()
|
|
```
|
|
|
|
Objective-C Example
|
|
===================
|
|
```objective-c
|
|
SocketIOClient* socket = [[SocketIOClient alloc] initWithSocketURL:@"localhost:8080" options:nil];
|
|
|
|
[socket on: @"connect" callback: ^(NSArray* data, void (^ack)(NSArray*)) {
|
|
NSLog(@"connected");
|
|
[socket emitObjc:@"echo" withItems:@[@"echo test"]];
|
|
[[socket emitWithAckObjc:@"ackack" withItems:@[@"test"]] onAck:0 withCallback:^(NSArray* data) {
|
|
NSLog(@"Got data");
|
|
}];
|
|
}];
|
|
|
|
```
|
|
|
|
Detailed Example
|
|
================
|
|
A more detailed example can be found [here](https://github.com/nuclearace/socket.io-client-swift-example)
|
|
|
|
License
|
|
=======
|
|
MIT
|