CocoaAsyncSocket README

The project's README from github.com/robbiehanson/CocoaAsyncSocket. As one markdown file: README.md.

CocoaAsyncSocket

CocoaAsyncSocket provides easy-to-use and powerful asynchronous socket libraries for macOS, iOS, and tvOS. The classes are described below.

Installation

CocoaPods

Install using CocoaPods by adding this line to your Podfile:

use_frameworks! # Add this if you are targeting iOS 8+ or using Swift
pod 'CocoaAsyncSocket'

Carthage

CocoaAsyncSocket is Carthage compatible. To include it add the following line to your Cartfile

github "robbiehanson/CocoaAsyncSocket" "master"

The project is currently configured to build for iOS, tvOS and Mac. After building with carthage the resultant frameworks will be stored in:

Carthage/Build/iOS/CocoaAsyncSocket.framework
Carthage/Build/tvOS/CocoaAsyncSocket.framework
Carthage/Build/Mac/CocoaAsyncSocket.framework

Select the correct framework(s) and drag it into your project.

Swift Package Manager

Simply add the package dependency to your Package.swift and depend on "CocoaAsyncSocket" in the necessary targets:

dependencies: [
    .package(url: "https://github.com/robbiehanson/CocoaAsyncSocket", from: "7.6.4")
]

Manual

You can also include it into your project by adding the source files directly, but you should probably be using a dependency manager to keep up to date.

Importing

Using Objective-C:

// When using Clang Modules:
@import CocoaAsyncSocket; 

// or when not:
#import "GCDAsyncSocket.h" // for TCP
#import "GCDAsyncUdpSocket.h" // for UDP

Using Swift:

import CocoaAsyncSocket

TCP

GCDAsyncSocket is a TCP/IP socket networking library built atop Grand Central Dispatch. Here are the key features available:

Native Objective-C, fully self-contained in one class.
No need to muck around with sockets or streams. This class handles everything for you.
Full delegate support
Errors, connections, read completions, write completions, progress, and disconnections all result in a call to your delegate method.
Queued non-blocking reads and writes, with optional timeouts.
You tell it what to read or write, and it handles everything for you. Queueing, buffering, and searching for termination sequences within the stream - all handled for you automatically.
Automatic socket acceptance.
Spin up a server socket, tell it to accept connections, and it will call you with new instances of itself for each connection.
Support for TCP streams over IPv4 and IPv6.
Automatically connect to IPv4 or IPv6 hosts. Automatically accept incoming connections over both IPv4 and IPv6 with a single instance of this class. No more worrying about multiple sockets.
Support for TLS / SSL
Secure your socket with ease using just a single method call. Available for both client and server sockets.
Fully GCD based and Thread-Safe
It runs entirely within its own GCD dispatch_queue, and is completely thread-safe. Further, the delegate methods are all invoked asynchronously onto a dispatch_queue of your choosing. This means parallel operation of your socket code, and your delegate/processing code.

UDP

GCDAsyncUdpSocket is a UDP/IP socket networking library built atop Grand Central Dispatch. Here are the key features available:

Native Objective-C, fully self-contained in one class.
No need to muck around with low-level sockets. This class handles everything for you.
Full delegate support.
Errors, send completions, receive completions, and disconnections all result in a call to your delegate method.
Queued non-blocking send and receive operations, with optional timeouts.
You tell it what to send or receive, and it handles everything for you. Queueing, buffering, waiting and checking errno - all handled for you automatically.
Support for IPv4 and IPv6.
Automatically send/recv using IPv4 and/or IPv6. No more worrying about multiple sockets.
Fully GCD based and Thread-Safe
It runs entirely within its own GCD dispatch_queue, and is completely thread-safe. Further, the delegate methods are all invoked asynchronously onto a dispatch_queue of your choosing. This means parallel operation of your socket code, and your delegate/processing code.

For those new(ish) to networking, it's recommended you read the wiki.
Sockets might not work exactly like you think they do...

Still got questions? Try the CocoaAsyncSocket Mailing List.

Love the project? Wanna buy me a ☕️ ? (or a 🍺 😀 ):

Searching Database…

12.4K ·GitHub

CocoaAsyncSocket

What is this?

CocoaAsyncSocket is an asynchronous socket networking library for macOS, iOS, and tvOS, providing TCP and UDP classes built on Grand Central Dispatch.

Is this a framework or just a couple of classes I drop in?

It is a lightweight library with two main self-contained Objective-C classes, GCDAsyncSocket for TCP and GCDAsyncUdpSocket for UDP, not a full framework.

How do I add it to my project?

Install via CocoaPods, Carthage, or Swift Package Manager by adding the dependency, or just drag the source files in manually.

Do I need anything beyond Xcode to use it?

No external runtime dependencies are required; it works directly with Objective-C or Swift import and relies on GCD, which is built into the Apple SDKs.

Is there anything tricky about how sockets behave here?

The README itself warns that sockets don't necessarily work the way newcomers expect, and recommends reading the project wiki before diving in.

Does it support both IPv4 and IPv6?

Yes, both the TCP and UDP classes automatically support IPv4 and IPv6 connections without needing separate sockets.

Which Apple platforms does it run on?

It builds for macOS, iOS, and tvOS.

Does GCDAsyncSocket support encrypted connections?

Yes, it supports TLS/SSL with a single method call, available for both client and server sockets.

How does it handle threading and callbacks?

It runs entirely within its own GCD dispatch queue and is fully thread-safe, invoking delegate methods asynchronously on a dispatch queue of your choosing for parallel operation.

What happens when I spin up a server socket?

GCDAsyncSocket supports automatic socket acceptance: you tell it to accept connections and it calls your delegate with a new instance of itself for each incoming connection.

What are similar projects?

AFNetworking, firebase-ios-sdk, Mantle, fmdb, libuv, SwiftyJSON, SVProgressHUD, Charts

Which topics is it in?

ipv4, ipv6, libraries, socket, asynchronous, udp, tcp, tvos, objective-c, apple, swift, sdk

Creator: robbiehanson
Size: 2.2 MB
Stars: 12.4K
Updated: CommitMay 12 Release7.6.5Dec 13
Age: 14y
Commits · 90 Days