APNS HTTP/2 support library.
Copyright (c) 2015-2016 Silent Circle
Authors: Edwin Fine (efine@silentcircle.com).
This is the next format after the v2 binary format, v3 if you like.
See https://developer.apple.com for more information.
base64_urlencoded() = bstring()
bstring() = binary()
http2_hdrs() = [http2_hdr()]
http2_req() = {http2_hdrs(), http2_req_body()}
http2_req_body() = bstring()
http2_rsp() = {http2_hdrs(), http2_rsp_body()}
http2_rsp_body() = undefined | [bstring()]
jwt() = base64_urlencoded()
parsed_rsp() = [parsed_rsp_val()]
parsed_rsp_val() = {uuid, uuid_str()} | {status, bstring()} | {status_desc, bstring()} | {reason, bstring()} | {reason_desc, bstring()} | {timestamp, non_neg_integer() | undefined} | {timestamp_desc, bstring() | undefined} | {body, term()}
req_opt() = {authorization, jwt()} | {uuid, uuid_str()} | {expiration, non_neg_integer()} | {priority, non_neg_integer()} | {topic, bstring()} | {collapse_id, bstring()} | {thread_id, bstring()}
req_opts() = [req_opt()]
uuid_str() = bstring()
| host_port/1 | Returns a default {Host, Port} for prod or dev APNS environment. |
| make_req/3 | Create an HTTP/2 request ready to send. |
| make_req_hdrs/4 | Create HTTP/2 request headers for an APNS request. |
| make_ssl_opts/2 | Return default SSL options for APNS HTTP/2. |
| make_uuid/0 | Make a UUID suitable for APNS id header. |
| parse_resp/1 | Parse HTTP/2 response body and headers. |
| parse_resp_body/1 | Parse APNS HTTP/2 response body. |
| reason_desc/1 | Map APNS HTTP/2 reason to text description. |
| status_desc/1 | Map HTTP/2 status code to textual description. |
host_port(Env) -> HostPort
Env = prod | devHostPort = {Host, Port}Host = string()Port = non_neg_integer()
Returns a default {Host, Port} for prod or dev APNS environment.
make_req(Token, JSON, Opts) -> Req
Token = string() | bstring()JSON = string() | bstring()Opts = req_opts()Req = http2_req()
Create an HTTP/2 request ready to send.
TokenJSONOpts{authorization, jwt()}- The provider token that authorizes APNs to send push notifications for the specified topics. The token is in Base64URL-encoded JWT format. When the provider certificate is used to establish a connection, this request header is ignored.
{uuid, uuid_str()}- A canonical UUID that identifies the notification. If there is
an error sending the notification, APNs uses this value to
identify the notification to your server. The canonical form is
32 lowercase hexadecimal digits, displayed in five groups
separated by hyphens in the form 8-4-4-4-12. An example UUID
is
123e4567-e89b-12d3-a456-42665544000. If you omit this header, a new UUID is created by APNs and returned in the response. {expiration, non_neg_integer()}- A UNIX epoch date expressed in seconds (UTC). This header
identifies the date when the notification is no longer valid and
can be discarded. If this value is nonzero, APNs stores the
notification and tries to deliver it at least once, repeating the
attempt as needed if it is unable to deliver the notification the
first time. If the value is
0, APNs treats the notification as if it expires immediately and does not store the notification or attempt to redeliver it. {priority, non_neg_integer()}- The priority of the notification. Specify one of the following
values:
10–Send the push message immediately. Notifications with this priority must trigger an alert, sound, or badge on the target device. It is an error to use this priority for a push notification that contains only the content-available key.5—Send the push message at a time that takes into account power considerations for the device. Notifications with this priority might be grouped and delivered in bursts. They are throttled, and in some cases are not delivered. If you omit this header, the APNs server sets the priority to10.
{topic, string() | bstring()}- The topic of the remote notification, which is typically the bundle ID for your app. The certificate you create in Member Center must include the capability for this topic. If your certificate includes multiple topics, you must specify a value for this header. If you omit this header and your APNs certificate does not specify multiple topics, the APNs server uses the certificate’s Subject as the default topic.
{collapse_id, string() | bstring()}- Multiple notifications with same collapse identifier are displayed to the user as a single notification. The value should not exceed 64 bytes.
{thread_id, string() | bstring()}- When displaying notifications, the system visually groups
notifications with the same thread identifier together. For
remote notifications, the value of the
threadIdentifierproperty is set to the value of this request header.
APNSIdReturns {http2_hdrs(), http2_req_body()}.
See also: apns_json.
make_req_hdrs(Method, Path, Scheme, Opts) -> Headers
Method = string() | bstring()Path = string() | bstring()Scheme = string() | bstring()Opts = req_opts()Headers = http2_hdrs()
Create HTTP/2 request headers for an APNS request.
Opts is a property list of supported optional headers.
See also: make_req/3.
make_ssl_opts(CertFile, KeyFile) -> Opts
CertFile = string()KeyFile = string()Opts = [{atom(), term()}]
Return default SSL options for APNS HTTP/2.
make_uuid() -> uuid_str()
Make a UUID suitable for APNS id header.
The return value is a binary string comprising 32 lowercase hexadecimal digits, displayed in five groups separated by hyphens in the form 8-4-4-4-12.
>make_uuid().
<<"123e4567-e89b-12d3-a456-42665544000">>
parse_resp(Resp) -> Result
Resp = http2_rsp()Result = parsed_rsp()
Parse HTTP/2 response body and headers. Return proplist with parsed body, uuid, status, and other information.
parse_resp_body(RespBody) -> Result
RespBody = http2_rsp_body()Reason = bstring()Timestamp = undefined | non_neg_integer()EJSON = apns_json:json_term()Result = [] | [{Reason, EJSON}] | [{Reason, Timestamp, EJSON}]
Parse APNS HTTP/2 response body.
reason_desc(Reason) -> Desc
Map APNS HTTP/2 reason to text description.
status_desc(Status) -> Desc
Map HTTP/2 status code to textual description.