/ 
POE-Component-WebService-HtmlKitCom-FavIconFromImage-0.001
/ POE::Component::WebService::HtmlKitCom::FavIconFromImage

NAME

POE::Component::WebService::HtmlKitCom::FavIconFromImage - non-blocking wrapper around WebService::HtmlKitCom::FavIconFromImage

SYNOPSIS

use strict;
use warnings;

use POE qw(Component::WebService::HtmlKitCom::FavIconFromImage);

my $poco = POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn;

POE::Session->create(
    package_states => [ main => [qw(_start result)] ],
);

$poe_kernel->run;

sub _start {
    $poco->favicon( {
            image => 'some_image.jpg',
            file  => 'out.zip',
            event => 'result',
        }
    );
}

sub result {
    my $in_ref = $_[ARG0];

    if ( exists $in_ref->{error} ) {
        print "Got error: $in_ref->{error}\n";
    }
    else {
        print "Done! I saved your favicon in out.zip file\n";
    }

    $poco->shutdown;
}

Using event based interface is also possible of course.

DESCRIPTION

The module is a non-blocking wrapper around WebService::HtmlKitCom::FavIconFromImage which provides interface to generate favicons from regular images. What's a "favicon"? See http://en.wikipedia.org/wiki/Favicon

CONSTRUCTOR

spawn

my $poco = POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn;

POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn(
    alias => 'fav',
    obj_args => { timeout => 30 },
    options => {
        debug => 1,
        trace => 1,
        # POE::Session arguments for the component
    },
    debug => 1, # output some debug info
);

The spawn method returns a POE::Component::WebService::HtmlKitCom::FavIconFromImage object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn(
    alias => 'fav'
);

Optional. Specifies a POE Kernel alias for the component.

obj_args

POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn(
    obj_args => { timeout => 10 },
);

Optional. Takes a hashref as a value which will be be dereferenced directly into WebService::HtmlKitCom::FavIconFromImage constructor. See documentation for WebService::HtmlKitCom::FavIconFromImage's constructor for possible arguments. Defaults to: {} (default constructor)

options

my $poco = POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn(
    options => {
        trace => 1,
        default => 1,
    },
);

Optional. A hashref of POE Session options to pass to the component's session.

debug

my $poco = POE::Component::WebService::HtmlKitCom::FavIconFromImage->spawn(
    debug => 1
);

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

favicon

$poco->favicon( {
        event   => 'event_for_output',
        image   => 'some_pic.jpg',
        file    => 'out.zip',
        animate => 1,
        text    => 'ugly scrolling text',
        _blah   => 'pooh!',
        session => 'other',
    }
);

Takes a hashref as an argument, does not return a sensible return value. See favicon event's description for more information.

session_id

my $poco_id = $poco->session_id;

Takes no arguments. Returns component's session ID.

shutdown

$poco->shutdown;

Takes no arguments. Shuts down the component.

ACCEPTED EVENTS

favicon

$poe_kernel->post( fav => favicon => {
        event   => 'event_for_output',
        image   => 'some_pic.jpg',
        file    => 'out.zip',
        animate => 1,
        text    => 'ugly scrolling text',
        _blah   => 'pooh!',
        session => 'other',
    }
);

Instructs the component to create a favicon. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:

event

{ event => 'results_event', }

Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.

image

{ image => 'some_pic.jpg' }

Mandatory. Takes a scalar as a value which must be a filename of the image file you from which you want to make your favicon.

file

{'some_pic.jpg', file => 'out.zip' }

Optional. If file argument is specified the archive containing the favicon will be saved into the file name of which is the value of file argument. By default not specified and you'll have to fish out the archive from the return value (see "OUTPUT" section)

animate

{ animate => 1 }

Optional. Takes either true or false values. When set to a true value will ask the site to make an "animated" icon. Defaults to: 0

text

{ text => 'Zoffix ROXORZ!' }

Optional. If animation did not make your favicon icon ugly enough then specify the text argument which ask the site to add it as "Scrolling text" into your favicon. Defaults to: '' (no text)

session

{ session => 'other' }

{ session => $other_session_reference }

{ session => $other_session_ID }

Optional. Takes either an alias, reference or an ID of an alternative session to send output to.

user defined

{
    _user    => 'random',
    _another => 'more',
}

Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.

shutdown

$poe_kernel->post( fav => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT

$VAR1 = {
    response => bless( { blah blah}, 'HTTP::Response' ),
    image   => 'foos.jpg',
    file    => 'out.zip',
    '_blah' => 'foos'
};

The event handler set up to handle the event which you've specified in the event argument to Efavicon() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

response

{ response => bless( { blah blah}, 'HTTP::Response' ), }

The response key will contain an HTTP::Response object which was obtained while retrieving your favicon. Unless you specified the file argument to favicon event/method you'll have to fish your favicon from this HTTP::Response object (it will be a 'zip' archive).

error

{ error => 'Network error: 500 read timeout' }

If error key is present it means your request failed for whatever reason. The value will be the error message describing the failure.

valid arguments from favicon

{ file => 'out.zip', ...etc }

Any valid arguments which can be given to favicon method/event (e.g. file, text, etc) will be present in output with the same values you've set to them.

user defined

{ '_blah' => 'foos' }

Any arguments beginning with _ (underscore) passed into the favicon() event/method will be present intact in the result.

SEE ALSO

POE, WebService::HtmlKitCom::FavIconFromImage

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-poe-component-webservice-htmlkitcom-faviconfromimage at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WebService-HtmlKitCom-FavIconFromImage. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc POE::Component::WebService::HtmlKitCom::FavIconFromImage

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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