Skip to content

Commit 5dd3383

Browse files
kylebrowningkylebrowning
committed
Cleanup documentation.
1 parent fa134d0 commit 5dd3383

File tree

4 files changed

+95
-65
lines changed

4 files changed

+95
-65
lines changed

‎Sources/APNSwift/APNSwiftConnection.swift‎

Lines changed: 72 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,26 @@ import NIOHTTP2
1818
import NIOSSL
1919

2020
public final class APNSwiftConnection {
21+
22+
/**
23+
APNSwift Connect method. Used to establish a connection with Apple Push Notification service.
24+
- Parameter configuration: APNSwiftConfiguration struct.
25+
- Parameter eventLoop: eventLoop to open the connection on.
26+
27+
### Usage Example: ###
28+
```
29+
let signer = try! APNSwiftSigner(filePath: "/Users/kylebrowning/Downloads/AuthKey_9UC9ZLQ8YW.p8")
30+
31+
let apnsConfig = APNSwiftConfiguration(keyIdentifier: "9UC9ZLQ8YW",
32+
teamIdentifier: "ABBM6U9RM5",
33+
signer: signer,
34+
topic: "com.grasscove.Fern",
35+
environment: .sandbox)
36+
37+
let apns = try APNSwiftConnection.connect(configuration: apnsConfig, on: group.next()).wait()
38+
```
39+
*/
40+
2141
public static func connect(configuration: APNSwiftConfiguration, on eventLoop: EventLoop) -> EventLoopFuture<APNSwiftConnection> {
2242
let bootstrap = ClientBootstrap(group: eventLoop)
2343
.channelOption(ChannelOptions.socket(IPPROTO_TCP, TCP_NODELAY), value: 1)
@@ -34,65 +54,79 @@ public final class APNSwiftConnection {
3454
channel.close(mode: .all, promise: nil)
3555
return channel.eventLoop.makeFailedFuture(error)
3656
}
37-
}
38-
57+
}
58+
3959
return bootstrap.connect(host: configuration.url.host!, port: 443).flatMap { channel in
4060
return channel.pipeline.handler(type: HTTP2StreamMultiplexer.self).map { multiplexer in
4161
return APNSwiftConnection(channel: channel, multiplexer: multiplexer, configuration: configuration)
4262
}
4363
}
4464
}
45-
65+
4666
public let multiplexer: HTTP2StreamMultiplexer
4767
public let channel: Channel
4868
public let configuration: APNSwiftConfiguration
49-
69+
5070
public init(channel: Channel, multiplexer: HTTP2StreamMultiplexer, configuration: APNSwiftConfiguration) {
5171
self.channel = channel
5272
self.multiplexer = multiplexer
5373
self.configuration = configuration
5474
}
55-
56-
public func send<Notification>(_ notification: Notification, to deviceToken: String, with customEncoder: JSONEncoder? = nil, expiration: Date? = nil, priority: Int? = nil, collapseIdentifier: String? = nil, topic: String? = nil) -> EventLoopFuture<Void>
75+
76+
/**
77+
APNSwiftConnection send method. Sends a notification to the desired deviceToken.
78+
- Parameter notification: the notification meta data and alert to send.
79+
- Parameter deviceToken: device token to send alert to.
80+
- Parameter encoder: customer JSON encoder if needed.
81+
- Parameter expiration: a date that the notificaiton expires.
82+
- Parameter priority: priority to send the notification with.
83+
- Parameter collapseIdentifier: a collapse identifier to use for grouping notifications
84+
- Parameter topic: the bundle identifier that this notification belongs to.
85+
86+
For more information see:
87+
[Retrieve Your App's Device Token](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns#2942135)
88+
### Usage Example: ###
89+
```
90+
let apns = APNSwiftConnection.connect()
91+
let expiry = Date().addingTimeInterval(5)
92+
try apns.send(notification, to: "b27a07be2092c7fbb02ab5f62f3135c615e18acc0ddf39a30ffde34d41665276", with: JSONEncoder(), expiration: expiry, priority: 10, collapseIdentifier: "huro2").wait()
93+
```
94+
*/
95+
public func send<Notification>(_ notification: Notification, to deviceToken: String, with encoder: JSONEncoder = JSONEncoder(), expiration: Date? = nil, priority: Int? = nil, collapseIdentifier: String? = nil, topic: String? = nil) -> EventLoopFuture<Void>
5796
where Notification: APNSwiftNotification {
58-
let streamPromise = channel.eventLoop.makePromise(of: Channel.self)
59-
multiplexer.createStreamChannel(promise: streamPromise) { channel, streamID in
60-
let handlers: [ChannelHandler] = [
61-
HTTP2ToHTTP1ClientCodec(streamID: streamID, httpProtocol: .https),
62-
APNSwiftRequestEncoder<Notification>(deviceToken: deviceToken, configuration: self.configuration, expiration: expiration, priority: priority, collapseIdentifier: collapseIdentifier),
63-
APNSwiftResponseDecoder(),
64-
APNSwiftStreamHandler(),
65-
]
66-
return channel.pipeline.addHandlers(handlers)
67-
}
68-
69-
let responsePromise = channel.eventLoop.makePromise(of: Void.self)
70-
let data: Data
71-
if let customEncoder = customEncoder {
72-
data = try! customEncoder.encode(notification)
73-
} else {
74-
data = try! JSONEncoder().encode(notification)
75-
}
76-
77-
var buffer = ByteBufferAllocator().buffer(capacity: data.count)
78-
buffer.writeBytes(data)
79-
let context = APNSwiftRequestContext(
80-
request: buffer,
81-
responsePromise: responsePromise
82-
)
83-
84-
return streamPromise.futureResult.flatMap { stream in
85-
responsePromise.futureResult.whenComplete { _ in }
86-
return stream.writeAndFlush(context)
97+
let streamPromise = channel.eventLoop.makePromise(of: Channel.self)
98+
multiplexer.createStreamChannel(promise: streamPromise) { channel, streamID in
99+
let handlers: [ChannelHandler] = [
100+
HTTP2ToHTTP1ClientCodec(streamID: streamID, httpProtocol: .https),
101+
APNSwiftRequestEncoder<Notification>(deviceToken: deviceToken, configuration: self.configuration, expiration: expiration, priority: priority, collapseIdentifier: collapseIdentifier),
102+
APNSwiftResponseDecoder(),
103+
APNSwiftStreamHandler(),
104+
]
105+
return channel.pipeline.addHandlers(handlers)
106+
}
107+
108+
let responsePromise = channel.eventLoop.makePromise(of: Void.self)
109+
let data: Data = try! encoder.encode(notification)
110+
111+
var buffer = ByteBufferAllocator().buffer(capacity: data.count)
112+
buffer.writeBytes(data)
113+
let context = APNSwiftRequestContext(
114+
request: buffer,
115+
responsePromise: responsePromise
116+
)
117+
118+
return streamPromise.futureResult.flatMap { stream in
119+
responsePromise.futureResult.whenComplete { _ in }
120+
return stream.writeAndFlush(context)
87121
}.flatMap {
88122
responsePromise.futureResult
89-
}
123+
}
90124
}
91-
125+
92126
var onClose: EventLoopFuture<Void> {
93127
return channel.closeFuture
94128
}
95-
129+
96130
public func close() -> EventLoopFuture<Void> {
97131
return channel.close(mode: .all)
98132
}

‎Sources/APNSwift/APNSwiftErrors.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ public struct APNSwiftError {
1919
public enum ResponseError: Error {
2020
case badRequest(ResponseErrorMessage)
2121
}
22-
// This is used to decode the response from Apple.
22+
/// This is used to decode the response from Apple.
2323
public struct ResponseStruct: Codable {
2424
public let reason: ResponseErrorMessage
2525
}

‎Sources/APNSwift/APNSwiftRequest.swift‎

Lines changed: 21 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -33,16 +33,15 @@ public struct APNSwiftPayload: Encodable {
3333

3434
/**
3535
Initialize an APNSwiftPayload
36-
- Parameters:
37-
- alert: The alert which will be display to the user.
38-
- badge: The number the push notification will bump the apps badge number to.
39-
- sound: A normal, or critical alert.
40-
- hasContentAvailable: When this key is present, the system wakes up your app in the background and
36+
- Parameter alert: The alert which will be display to the user.
37+
- Parameter badge: The number the push notification will bump the apps badge number to.
38+
- Parameter sound: A normal, or critical alert.
39+
- Parameter hasContentAvailable: When this key is present, the system wakes up your app in the background and
4140
delivers the notification to its app delegate.
42-
- hasMutableContent: When this key is present, the system will pass your notification to the
41+
- Parameter hasMutableContent: When this key is present, the system will pass your notification to the
4342
notification service app extension before delivery.
44-
- category: provide this string to define a category for your app.
45-
- threadID: Provide a thread value to group notifications.
43+
- Parameter category: provide this string to define a category for your app.
44+
- Parameter threadID: Provide a thread value to group notifications.
4645

4746
For more information see:
4847
[Payload Key Reference](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html#)
@@ -85,20 +84,19 @@ public struct APNSwiftPayload: Encodable {
8584

8685
/**
8786
This structure provides the data structure for an APNS Alert
88-
- Parameters:
89-
- title: The title to be displayed to the user.
90-
- subtitle: The subtitle to be displayed to the user.
91-
- body: The body of the push notification.
92-
- titleLocKey: The key to a title string in the Localizable.strings file for the current
87+
- Parameter title: The title to be displayed to the user.
88+
- Parameter subtitle: The subtitle to be displayed to the user.
89+
- Parameter body: The body of the push notification.
90+
- Parameter titleLocKey: The key to a title string in the Localizable.strings file for the current
9391
localization.
94-
- titleLocArgs: Variable string values to appear in place of the format specifiers in
92+
- Parameter titleLocArgs: Variable string values to appear in place of the format specifiers in
9593
title-loc-key.
96-
- actionLocKey: The string is used as a key to get a localized string in the current localization
94+
- Parameter actionLocKey: The string is used as a key to get a localized string in the current localization
9795
to use for the right button’s title instead of “View”.
98-
- locKey: A key to an alert-message string in a Localizable.strings file for the current
96+
- Parameter locKey: A key to an alert-message string in a Localizable.strings file for the current
9997
localization (which is set by the user’s language preference).
100-
- locArgs: Variable string values to appear in place of the format specifiers in loc-key.
101-
- launchImage: The filename of an image file in the app bundle, with or without the filename
98+
- Parameter locArgs: Variable string values to appear in place of the format specifiers in loc-key.
99+
- Parameter launchImage: The filename of an image file in the app bundle, with or without the filename
102100
extension.
103101

104102
For more information see:
@@ -141,10 +139,9 @@ public struct APNSwiftPayload: Encodable {
141139

142140
/**
143141
Initialize an APNSSoundDictionary
144-
- Parameters:
145-
- critical: The critical alert flag. Set to true to enable the critical alert.
146-
- sound: The apps path to a sound file.
147-
- volume: The volume for the critical alert’s sound. Set this to a value between 0.0 (silent) and 1.0 (full volume).
142+
- Parameter critical: The critical alert flag. Set to true to enable the critical alert.
143+
- Parameter sound: The apps path to a sound file.
144+
- Parameter volume: The volume for the critical alert’s sound. Set this to a value between 0.0 (silent) and 1.0 (full volume).
148145

149146
For more information see:
150147
[Payload Key Reference](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html#)
@@ -162,9 +159,8 @@ public struct APNSwiftPayload: Encodable {
162159
}
163160
/**
164161
An enum to define how to use sound.
165-
- Parameters:
166-
- string: use this for a normal alert sound
167-
- critical: use for a critical alert type
162+
- Parameter string: use this for a normal alert sound
163+
- Parameter critical: use for a critical alert type
168164
*/
169165
public enum APNSwiftSoundType: Encodable {
170166
case normal(String)

‎Sources/APNSwiftExample/main.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ let notification = AcmeNotification(acme2: ["bang", "whiz"], aps: aps)
5555

5656
do {
5757
let expiry = Date().addingTimeInterval(5)
58-
try apns.send(notification, to: "b27a07be2092c7fbb02ab5f62f3135c615e18acc0ddf39a30ffde34d41665276", with: JSONEncoder(), expiration: expiry, priority: 10, collapseIdentifier: "huro2").wait()
58+
try apns.send(notification, to: "b693f99efa926bcf9977adae75bc88a97988365f49e4c6abf94aa659a4d87a6b", expiration: expiry, priority: 10).wait()
5959
} catch {
6060
print(error)
6161
}

0 commit comments

Comments
 (0)