Snapper-swift
Snapper-core client by Swift 3.0 for iOS/OS X
##Example
let snapper = SnapperClient(socketURL: "snapper.project.bi/websocket", options: [.Log(true), .ConnectParams(["token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NWM4MTdmOGU3MTVmYTk5MmExOTNlOTkiLCJleHAiOjE0NTA5MzYwODd9.Y9gk3d3YTE3loyUxWSxiVJzHjhe12bn5O5qGsuJ89JE"])])
snapper.connect()
snapper.on("connect") { (data) -> Void in
print("connect")
print(self.snapper.status)
}
snapper.on("error") { (data) -> Void in
}
snapper.on("reconnect") { (data) -> Void in
}
snapper.message { (message: SnapperMessage) -> Void in
print(message.items)
self.snapper.replay(message.id)
}
##Features
- Supports engine.io
- Supports Polling and WebSockets
- Supports TLS/SSL
##Installation Requires Swift 2/Xcode 7
Manually (iOS 7+)
- Copy the Source folder into your Xcode project. (Make sure you add the files to your target(s))
- If you plan on using this from Objective-C, read this on exposing Swift code to Objective-C.
Swift Package Manager
Add the project as a dependency to your Package.swift:
import PackageDescription
let package = Package(
name: "YourSocketIOProject",
dependencies: [
.Package(url: "https://github.com/socketio/socket.io-client-swift", majorVersion: 4)
]
)
Then import import SocketIOClientSwift
.
Carthage
Add this line to your Cartfile
:
github "teambition/Snapper-swift"
Run carthage update --platform ios,macosx
.
CocoaPods 0.36.0 or later (iOS 8+)
Create Podfile
and add pod 'Socket.IO-Client-Swift'
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!
pod 'Snapper-swift'
Install pods:
$ pod install
Import the module:
Swift:
import Socket_IO_Client_Swift
##API Constructors
init(var socketURL: String, options: Set<SocketIOClientOption> = [])
- Creates a new SocketIOClient. opts is a Set of SocketIOClientOption. If your socket.io server is secure, you need to specify https
in your socketURL.
convenience init(socketURL: String, options: NSDictionary?)
- Same as above, but meant for Objective-C. See Options on how convert between SocketIOClientOptions and dictionary keys.
Options
All options are a case of SocketIOClientOption. To get the Objective-C Option, convert the name to lowerCamelCase.
case ConnectParams([String: AnyObject]) // Dictionary whose contents will be passed with the connection.
case Reconnects(Bool) // Whether to reconnect on server lose. Default is `true`
case ReconnectAttempts(Int) // How many times to reconnect. Default is `-1` (infinite tries)
case ReconnectWait(Int) // Amount of time to wait between reconnects. Default is `10`
case ForcePolling(Bool) // `true` forces the client to use xhr-polling. Default is `false`
case ForceNew(Bool) // Will a create a new engine for each connect. Useful if you find a bug in the engine related to reconnects
case ForceWebsockets(Bool) // `true` forces the client to use WebSockets. Default is `false`
case Nsp(String) // The namespace to connect to. Must begin with /. Default is `/`
case Cookies([NSHTTPCookie]) // An array of NSHTTPCookies. Passed during the handshake. Default is nil.
case Log(Bool) // If `true` socket will log debug messages. Default is false.
case Logger(SocketLogger) // Custom logger that conforms to SocketLogger. Will use the default logging otherwise.
case SessionDelegate(NSURLSessionDelegate) // Sets an NSURLSessionDelegate for the underlying engine. Useful if you need to handle self-signed certs. Default is nil.
case Path(String) // If the server uses a custom path. ex: `"/swift"`. Default is `""`
case ExtraHeaders([String: String]) // Adds custom headers to the initial request. Default is nil.
case HandleQueue(dispatch_queue_t) // The dispatch queue that handlers are run on. Default is the main queue.
case VoipEnabled(Bool) // Only use this option if you're using the client with VoIP services. Changes the way the WebSocket is created. Default is false
case Secure(Bool) // If the connection should use TLS. Default is false.
case SelfSigned(Bool) // Sets WebSocket.selfSignedSSL (Don't do this, iOS will yell at you)
Methods
on(event: String, callback: NormalCallback) -> NSUUID
- 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. Returns a unique id for the handler.once(event: String, callback: NormalCallback) -> NSUUID
- Adds a handler that will only be executed once. Returns a unique id for the handler.onAny(callback:((event: String, items: AnyObject?)) -> Void)
- Adds a handler for all events. It will be called on any received event.emit(event: String, _ items: AnyObject...)
- Sends a message. Can send multiple items.emit(event: String, withItems items: [AnyObject])
-emit
for Objective-CemitWithAck(event: String, _ items: AnyObject...) -> (timeoutAfter: UInt64, callback: (NSArray?) -> Void) -> Void
- Sends a message that requests an acknowledgement from the server. Returns a function which you can use to add a handler. See example. Note: The message is not sent until you call the returned function.emitWithAck(event: String, withItems items: [AnyObject]) -> (UInt64, (NSArray?) -> Void) -> Void
-emitWithAck
for Objective-C. Note: The message is not sent until you call the returned function.connect()
- Establishes a connection to the server. A "connect" event is fired upon successful connection.connect(timeoutAfter timeoutAfter: Int, withTimeoutHandler handler: (() -> Void)?)
- Connect to the server. If it isn't connected after timeoutAfter seconds, the handler is called.close()
- Closes the socket. Once a socket is closed it should not be reopened.reconnect()
- Causes the client to reconnect to the server.joinNamespace()
- Causes the client to join nsp. Shouldn't need to be called unless you change nsp manually.leaveNamespace()
- Causes the client to leave the nsp and go back to /off(event: String)
- Removes all event handlers for event.off(id id: NSUUID)
- Removes the event that corresponds to id.removeAllHandlers()
- Removes all handlers.
Client Events
connect
- Emitted when on a successful connection.disconnect
- Emitted when the connection is closed.error
- Emitted on an error.reconnect
- Emitted when the connection is starting to reconnect.reconnectAttempt
- Emitted when attempting to reconnect.
##Detailed Example A more detailed example can be found here
##License MIT