Daisuke Murase > AnyEvent-APNS-0.10 > AnyEvent::APNS

Download:
AnyEvent-APNS-0.10.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.10   Source  

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 ^

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.

syntax highlighting: