NAME

AnyEvent::APNS - Simple wrapper for Apple Push Notifications Service (APNS) provider

SYNOPSIS

    use AnyEvent::APNS;

    my $cv = AnyEvent->condvar;

    my $apns; $apns = AnyEvent::APNS->new(
        certificate => 'your apns certificate file',
        private_key => 'your apns private key file',
        sandbox     => 1,
        on_error    => sub { # something went wrong },
        on_connect  => sub {
            my $identifier = $apns->send( $device_token => {
                aps => {
                    alert => 'Message received from Bob',
                },
            });
        },
        on_error_response => sub {
            my ($identifier, $status) = @_;
            # something wrong
        },
    );
    $apns->connect;

    # disconnect and exit program as soon as possible after sending a message
    # otherwise $apns makes persistent connection with apns server
    $apns->handler->on_drain(sub {
        undef $_[0];
        $cv->send;
    });

    $cv->recv;

DESCRIPTION

This module helps you to create Apple Push Notifications Service (APNS) Provider.

NOTE FOR 0.01x USERS

From 0.02, this module does not connect in constructor. You should call connect method explicitly to connect server.

METHODS

new

Create APNS object.

    my $apns = AnyEvent::APNS->new(
        certificate => 'your apns certificate file',
        private_key => 'your apns private key file',
        sandbox     => 1,
        on_error    => sub { # something went wrong },
    );

Supported arguments are:

certificate => 'Str | ScalarRef'

    certificate => '/path/to/certificate_file',
    # or
    certificate => \$certificate,

Required. Either file path for certificate or scalar-ref of certificate data.

private_key => 'Str | ScalarRef'

    private_key => '/path/to/private_key',
    # or
    private_key => \$private_key,

Required. Either file path for private_key or scalar-ref of private-key data.

sandbox => 0|1

This is a flag indicate target service is provisioning (sandbox => 1) or distribution (sandbox => 0)

Optional (Default: 0)

on_error => $cb->($handle, $fatal, $message)

Callback to be called when something error occurs. This is wrapper for AnyEvent::Handle's on_error callbacks. Look at the document for more detail.

Optional (Default: just warn error)

on_eof => $cb->($handle)

Callback to be called when an end-of-file condition is detected.

Optional. (Default: use on_error instead. read AnyEvent::Handle for more detail)

on_connect => $cb->()

Callback to be called when connection established to apns server.

Optional (Default: empty coderef)

on_error_response => $cb->($identifier, $status)

Callback to be called when APNs detects notification malformed or otherwise unintelligible.

$status codes are documented here: http://developer.apple.com/library/ios/#DOCUMENTATION/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html

$identifier is the return value of send.

Optional (Default: ignore)

$apns->connect;

Connect to apns server.

$apns->send( $device_token, \%payload )

Send apns messages with \%payload to device specified $device_token.

    my $identifier = $apns->send( $device_token => {
        aps => {
            alert => 'Message received from Bob',
        },
    });

$device_token should be a binary 32bytes device token provided by iPhone SDK (3.0 or above)

\%payload should be a hashref suitable to apple document: http://developer.apple.com/iPhone/library/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/ApplePushService/ApplePushService.html

Note: If you involve multi-byte strings in \%payload, it should be utf8 decoded strings not utf8 bytes.

Store $identifier with your $device_token to react to on_error_response.

$apns->handler

Return AnyEvent::Handle object which is used to current established connection. It returns undef before connection completed.

TODO

• More correct error handling

• Auto reconnection

AUTHOR

Daisuke Murase <typester@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2009 by KAYAC Inc.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

cpanm AnyEvent::APNS

perl -MCPAN -e shell
install AnyEvent::APNS