1 <?php
2
3 /**
4 * Apple Push Notification Service
5 *
6 * Apple Push Notification service (APNs for short) transports and routes a notification from a given provider to a
7 * given device. A notification is a short message consisting of two major pieces of data: the device token and the
8 * payload.
9 *
10 * The device token is analogous to a phone number; it contains information that enables APNs to locate the device on
11 * which the client application is installed. APNs also uses it to authenticate the routing of a notification.
12 *
13 * The Apple is not guarantee delivery, you should not depend on the remote-notifications facility
14 * for delivering critical data to an application via the payload. And never include sensitive data in the payload.
15 *
16 * The payload specifies how the user of an application on a device is to
17 * be alerted.
18 *
19 * @license https://www.php.net/license/3_01.txt PHP 3.01
20 * @link https://libcapn.org/php-apn
21 *
22 */
23
24 /**
25 * APN_PRODUCTION Specifies that "production" server shall be used. This is the default mode
26 */
27 define('APN_PRODUCTION', 0);
28
29 /**
30 * Specifies that "sandbox" server shall be used
31 */
32 define('APN_SANDBOX', 1);
33
34 /**
35 * Creates a new Apple Push Notification resource which is needed to hold the data for a connection to
36 * Apple Push Notification/Feedback Service
37 *
38 * This function allocates memory which should be freed - call apn_free() function
39 * for it
40 *
41 * @category Apple Push Notification Service
42 * @return resource|null Returns a APNs link identifier on success or null on failure.
43 */
44 function apn_init() {}
45
46 /**
47 * Opens Apple Push Notification Service connection
48 *
49 * @see apn_close()
50 * @category Apple Push Notification Service
51 * @param resource $apn Resource returned by apn_init(). If a non-resource is used for the apn,
52 * an error of level E_WARNING will be emitted
53 * @param string|null $error A reference to return error message. Pass null, if message should not
54 * be returned
55 * @param int|null $errcode A reference to return error code. Pass null, if code should not
56 * be returned
57 * @return bool Returns TRUE on success or FALSE on failure
58 */
59 function apn_connect($apn, &$error, &$errcode){}
60
61 /**
62 * Closes Apple Push Notification/Feedback Service connection
63 *
64 * @see apn_connect()
65 * @category Apple Push Notification Service
66 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
67 * an error of level E_WARNING will be emitted
68 * @return void
69 */
70 function apn_close($apn){}
71
72 /**
73 * Frees memory associated with the apn identifier result
74 *
75 * @category Apple Push Notification Service
76 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
77 * an error of level E_WARNING will be emitted
78 * @return bool Returns TRUE on success or FALSE on failure
79 */
80 function apn_free($apn){}
81
82 /**
83 * Sets connection mode
84 *
85 * Each connection limited to one of two modes, each with its own assigned IP address:
86 *
87 * APN_PRODUCTION - Use the production mode when building the production version of the provider
88 * application. This mode uses gateway.push.apple.com, outbound TCP port 2195.
89 *
90 * APN_SANDBOX - Use the sandbox mode for initial development and testing of the provider
91 * application. It provides the same set of services as the production mode. The sandbox mode also acts
92 * as a virtual device, enabling simulated end-to-end testing. This mode uses
93 * gateway.sandbox.push.apple.com, outbound TCP port 2195.
94 *
95 * You must get separate certificates for the sandbox mode and the production mode.
96 *
97 * Default mode is :APN_PRODUCTION
98 *
99 * @category Apple Push Notification Service
100 * @since 1.0.0
101 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
102 * an error of level E_WARNING will be emitted
103 * @param int $mode Mode APN_PRODUCTION or APN_SANDBOX
104 */
105 function apn_set_mode($apn, $mode){}
106
107 /**
108 * Sets path to an SSL certificate which will be used to establish secure connection
109 *
110 * @category Apple Push Notification Service
111 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
112 * an error of level E_WARNING will be emitted
113 * @param string $certificate Path to a SSL certificate file
114 * @return bool Returns TRUE on success or FALSE on failure
115 */
116 function apn_set_certificate($apn, $certificate){}
117
118 /**
119 * Sets a path to a private key which will be used to establish secure connection
120 *
121 * @category Apple Push Notification Service
122 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
123 * an error of level E_WARNING will be emitted
124 * @param string $private_key Path to a private key file
125 * @param string|null $private_key_pass Private key passphrase or null
126 * @return bool Returns TRUE on success or FALSE on failure
127 */
128 function apn_set_private_key($apn, $private_key, $private_key_pass = null){}
129
130 /**
131 * Adds a device token
132 *
133 * Device token are used for identification of targets
134 * which will receive the notification
135 *
136 * @see apn_add_tokens()
137 * @category Apple Push Notification Service
138 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
139 * an error of level E_WARNING will be emitted
140 * @param string $token Device token
141 * @return bool Returns TRUE on success or FALSE on failure
142 */
143 function apn_add_token($apn, $token){}
144
145 /**
146 * Adds a device tokens
147 *
148 * Device token are used for identification of targets
149 * which will receive the notification
150 *
151 * @see apn_add_token()
152 * @category Apple Push Notification Service
153 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
154 * an error of level E_WARNING will be emitted
155 * @param array $tokens Device tokens
156 * @return bool Returns TRUE on success or FALSE on failure
157 */
158 function apn_add_tokens($apn, array $tokens){}
159
160 /**
161 * Set multiple apn options
162 *
163 * Valid options are:
164 *
165 * <ul>
166 * <li>mode - Sets connection mode</li>
167 * <li>certificate - path to an SSL certificate</li>
168 * <li>private_key - path to a private key</li>
169 * <li>private_key_pass - private key passphrase</li>
170 * <li>tokens - array of device tokens</li>
171 * </ul>
172 *
173 * @category Apple Push Notification Service
174 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
175 * an error of level E_WARNING will be emitted
176 * @param array $options An associative array specifying which options to set and their values
177 * @return bool Returns TRUE on success or FALSE on failure
178 */
179 function apn_set_array($apn, array $options){}
180
181 /**
182 * Sends push notification
183 *
184 * @category Apple Push Notification Service
185 * @param resource $apn Apple Push Notification Resource returned by apn_init(). If a non-resource is used for the apn,
186 * an error of level E_WARNING will be emitted
187 * @param resource $payload Apple Push Notification Payload Resource returned by apn_payload_init(). If a non-resource is used for the apn,
188 * an error of level E_WARNING will be emitted
189 * @param string|null $error A reference to return error message. Pass null, if message should not
190 * be returned
191 * @param int|null $errcode A reference to return error code. Pass null, if code should not
192 * be returned
193 * @return bool Returns TRUE on success or FALSE on failure
194 */
195 function apn_send($apn, $payload, &$error, &$errcode){}
196
197 /**
198 * Creates a new Apple Push Notification Payload resource
199 *
200 * This function allocates memory for which should be freed - call apn_payload_free() function
201 * for it
202 *
203 * @category Apple Push Notification Payload
204 * @return void
205 */
206 function apn_payload_init(){}
207
208 /**
209 * Frees memory associated with the payload identifier result
210 *
211 * @category Apple Push Notification Payload
212 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
213 * used for the apn, an error of level E_WARNING will be emitted
214 * @return bool Returns TRUE on success or FALSE on failure
215 */
216 function apn_payload_free($payload){}
217
218 /**
219 * Sets a number to display as a badge on the application icon
220 *
221 * If this property is not set, previously set value is not changed. To remove the badge,
222 * set the value to 0
223 *
224 * @category Apple Push Notification Payload
225 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
226 * used for the apn, an error of level E_WARNING will be emitted
227 * @param integer $badge A number to display as the badge
228 * @return bool Returns TRUE on success or FALSE on failure
229 */
230 function apn_payload_set_badge($payload, $badge){}
231
232 /**
233 * Sets expiration time of notification
234 *
235 * Expiration time is a fixed UNIX epoch date expressed in seconds (UTC) that identifies when the notification
236 * is no longer valid and can be discarded. You can specify zero or a value less than zero
237 * to request that APNs not store the notification at all.
238 * Default value is 0.
239 *
240 * @since 1.0.0
241 *
242 * @category Apple Push Notification Payload
243 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
244 * used for the apn, an error of level E_WARNING will be emitted
245 * @param integer $expiry Time in seconds
246 * @return bool Returns TRUE on success or FALSE on failure
247 */
248 function apn_payload_set_expiry($payload, $expiry){}
249
250 /**
251 * Sets a text of the alert message
252 *
253 * @category Apple Push Notification Payload
254 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
255 * used for the apn, an error of level E_WARNING will be emitted
256 * @param string $body Text. Must be a valid UTF-8 encoded Unicode string
257 * @return bool Returns TRUE on success or FALSE on failure
258 */
259 function apn_payload_set_body($payload, $body){}
260
261 /**
262 * Sets a name of a sound file in the application bundle
263 *
264 * This sound file is played as an alert. If the sound file doesn’t exist or default is specified as the value,
265 * the default alert sound is played
266 *
267 * @category Apple Push Notification Payload
268 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
269 * used for the apn, an error of level E_WARNING will be emitted
270 * @param string $sound Name of a sound file. Must be a valid UTF-8 encoded Unicode string
271 * @return bool Returns TRUE on success or FALSE on failure
272 */
273 function apn_payload_set_sound($payload, $sound){}
274
275 /**
276 * Sets a key used to get a localized alert-message string and an array of strings to appear in place of the
277 * format specifiers in `key`
278 *
279 * The `key` string can be formatted with %@ and %n$@ specifiers to take the variables specified in `args`
280 *
281 * @category Apple Push Notification Payload
282 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
283 * used for the apn, an error of level E_WARNING will be emitted
284 * @param string $localized_key Key of localized string
285 * @param array $args Array of string values to appear in place of the format specifiers in `key`
286 * @return bool Returns TRUE on success or FALSE on failure
287 */
288 function apn_payload_set_localized_key($payload, $localized_key, array $args = null){}
289
290 /**
291 * Sets a filename of an image file in the application bundle
292 *
293 * Filename may include or not include the extension. The image is used as the launch image when users tap
294 * the action button or move the action slider. If this property is not specified, the system either
295 * uses the previous one, uses the image identified by the UILaunchImageFile key in the application’s
296 * Info.plist file, or falls back to Default.png
297 *
298 * @category Apple Push Notification Payload
299 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
300 * used for the apn, an error of level E_WARNING will be emitted
301 * @param string $launch_image A filename of an image file
302 * @return bool Returns TRUE on success or FALSE on failure
303 */
304 function apn_payload_set_launch_image($payload, $launch_image){}
305
306 /**
307 * Sets a key used to get a localized string to use for the right button’s
308 * caption instead of "View"
309 *
310 * If the value is null, the system displays an alert with a single OK button that simply
311 * dismisses the alert when tapped
312 *
313 * @category Apple Push Notification Payload
314 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
315 * used for the apn, an error of level E_WARNING will be emitted
316 * @param string $localized_action_key Key for localized string
317 * @return bool Returns TRUE on success or FALSE on failure
318 */
319 function apn_payload_set_localized_action_key($payload, $localized_action_key){}
320
321 /**
322 * Adds a device token to payload
323 *
324 * Device token are used for identification of targets
325 * which will receive the notification
326 *
327 * @since 1.0.0
328 * @see apn_add_tokens()
329 * @see apn_payload_add_tokens()
330 * @category Apple Push Notification Payload
331 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
332 * used for the apn, an error of level E_WARNING will be emitted
333 * @param string $token Device token
334 * @return bool Returns TRUE on success or FALSE on failure
335 */
336 function apn_payload_add_token($payload, $token){}
337
338 /**
339 * Adds a device tokens to payload
340 *
341 * Device token are used for identification of targets
342 * which will receive the notification
343 *
344 * @since 1.0.0
345 * @see apn_add_token()
346 * @see apn_payload_add_token()
347 * @category Apple Push Notification Payload
348 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
349 * used for the apn, an error of level E_WARNING will be emitted
350 * @param array $tokens Device tokens
351 * @return bool Returns TRUE on success or FALSE on failure
352 */
353 function apn_payload_add_tokens($payload, array $tokens){}
354
355 /**
356 * Set multiple payload properties
357 *
358 * Valid properties are:
359 *
360 * <ul>
361 * <li>badge - number to display as a badge on the application icon</li>
362 * <li>sound - name of a sound file in the application bundle</li>
363 * <li>body - text of an alert message</li>
364 * <li>localized_key - key used to get a localized alert-message string</li>
365 * <li>localized_key_args - array of strings to appear in place of the format specifiers in `key`</li>
366 * <li>localized_action_key - key used to get a localized string for the right button’s
367 * caption instead of "View"</li>
368 * <li>launch_image - filename of an image file in the application bundle</li>
369 * <li>tokens - array of device tokens</li>
370 * <li>expiry - expiration time of notification</li>
371 * </ul>
372 *
373 * @category Apple Push Notification Payload
374 * @param resource $payload Apple Push Notification Resource returned by apn_payload_init(). If a non-resource is
375 * used for the apn, an error of level E_WARNING will be emitted
376 * @param array $properties An associative array specifying which payload properties to set and their values
377 * @return bool Returns TRUE on success or FALSE on failure
378 */
379 function apn_payload_set_array($payload, array $properties){}
380
381 /**
382 * Opens Apple Push Feedback Service connection
383 *
384 * @see apn_close()
385 * @category Apple Push Feedback Service
386 * @param resource $apn Resource returned by apn_init(). If a non-resource is used for the apn,
387 * an error of level E_WARNING will be emitted
388 * @param string|null $error A reference to return error message. Pass null, if message should not
389 * be returned
390 * @param int|null $errcode A reference to return error code. Pass null, if code should not
391 * be returned
392 * @return bool Returns TRUE on success or FALSE on failure
393 */
394 function apn_feedback_connect($apn, &$error, &$errcode){}
395
396
397 /**
398 * Returns array of device tokens which no longer exists
399 *
400 * @see apn_feedback_connect()
401 * @category Apple Push Feedback Service
402 * @param resource $apn Resource returned by apn_init(). If a non-resource is used for the apn,
403 * an error of level E_WARNING will be emitted
404 * @param string|null $error A reference to return error message. Pass null, if message should not
405 * be returned
406 * @param int|null $errcode A reference to return error code. Pass null, if code should not
407 * be returned
408 * @return array|null Returns array of devices token on success or null on failure
409 */
410 function apn_feedback($apn, &$error, &$errcode){}
411