The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-XMPP-Client-GTalk-0.01
River stage zero No dependents
++
/ Net::XMPP::Client::GTalk

NAME

Net::XMPP::Client::GTalk - This module provides an easy to use wrapper around the Net::XMPP class of modules for specific access to GTalk ( Both on Gmail and Google Apps ).

VERSION

Version 0.01

GLOBAL VARIABLES

our $COMMUNICATION ;

our $RECEIVE_CALLBACK ;

SYNOPSIS

This module provides an easy to use wrapper around the Net::XMPP class of modules for specific access to GTalk ( Both on Gmail and Google Apps ).

Example:

This example connects to GTalk and waits for a chat message from someone. It replies to that person with the chat message that it received. Additionally it will dump online buddies at regular intervals along with the contents of the message it receives.

You can quit this program by sending it the chat message 'exit'.

    use Net::XMPP::Client::GTalk    ;
    use Data::Dump qw( dump )       ;

    my $username ; # = '' ; Set GTalk username here [ WITHOUT '@gmail.com' ]. 
    my $password ; # = '' ; Set GTalk password here.


    unless( defined( $username ) and defined( $password ) ) { 
        die( "SET YOUR GTALK USERNAME AND PASSWORD ABOVE!\n" ) ;
    }

    # See options for domain below in documentation for new.
    my $ob = new Net::XMPP::Client::GTalk( 
        USERNAME   =>  $username         ,
        PASSWORD   =>  $password         ,
        );


    my $require_run = 1 ;
    my $iteration   = 1 ;
    while( $require_run ) { 

        my $message = $ob->wait_for_message( 60 ) ;

        unless( $message ) { 
            print "GOT NO MESSAGE - waiting longer\n" ;
        }

        if( $message->{ error } ) { 
            print "ERROR \n" ;
            next             ;
        } else { 
            dump( $message ) ;
        }

        if( $message->{ message } eq 'exit' ) { 
            print "Asked to exit by " . $message->{ from } . "\n" ;
            $message->{ message } = 'Exiting ... ' ;
            $require_run = 0 ;
        }

        $ob->send_message( $message->{ from }, $message->{ message } ) ;

        if( int( $iteration / 3 ) == ( $iteration / 3 ) ) { 
            my @online_buddies = @{ $ob->get_online_buddies() } ;
            dump( \@online_buddies ) ;
        }

        $iteration++ ;

    }


    exit() ;

USAGE NOTES

The NET::XMPP connection object is available through $object_of_Net_XMPP_Client_GTalk->{ RAW_CONNECTION } and can be used to call all functions of the NET::XMPP class of modules ( listed below ).

It should be noted, however, that calling the SetCallBacks function on the NET::XMPP object will cause wait_for_message to fail. SetCallBacks can be called indirectly through new as follows:

    my $ob = new Net::XMPP::Client::GTalk( 
        USERNAME     =>  $username         ,
        PASSWORD     =>  $password         ,
        DOMAIN       => 'gmail.com'        ,           # [ OPTIONAL ] [ DEFAULT gmail.com - set if other such as google apps domain ]
        SetCallBacks =>  { 
                 message     =>  \&function ,
                 presence    =>  \&function ,
                 iq          =>  \&function ,
                 send        =>  \&function ,
                 receive     =>  \&function ,
                 update      =>  \&function ,
          }                                ,
        RESOURCE     => 'My Chat Prog'     ,
    ) ;

Other than USERNAME and PASSWORD the other two parameters above are optional.

The presence_send function does NOT update the chat status. This is because the corresponding NET::XMPP functions do not work.

Additionally the following does NOT work and this module provides get_online_buddies as a work around.

    my $roster = $NET_XMPP_Connection->Roster();
    my $user   = $roster->online( 'somebuddy@gmail.com' );

The value of resource can be changed as shown above.

The connection to GTalk does not have to be explicitly disconnected as it is automatically done when this module object goes out of scope or when the program terminates. It is a BAD idea to do: $object_of_Net_XMPP_Client_GTalk->{ RAW_CONNECTION }->Disconnect();

Modules from which you can use functions include:

    Net::XMPP             
    Net::XMPP::Client
    Net::XMPP::Connection
    Net::XMPP::Debug
    Net::XMPP::IQ
    Net::XMPP::JID
    Net::XMPP::Message
    Net::XMPP::Namespaces
    Net::XMPP::Presence
    Net::XMPP::PrivacyLists
    Net::XMPP::Protocol
    Net::XMPP::Roster
    Net::XMPP::Stanza

THREADS: This module is NOT thread safe. To use it within a thread you need to require this module from within the thread.

WARNING: If the person you are sending a chat message to is not online then they will not receive an offline chat message, however, if they come online before the program terminates they will receive the chat.

EXPORT

This is a purely object-oriented module and does not export anything.

SUBROUTINES/METHODS

new

  Usage:                                                                                      

    my $ob = new Net::XMPP::Client::GTalk( 
        USERNAME     =>  $username         ,
        PASSWORD     =>  $password         ,
        DOMAIN       => 'gmail.com'        ,           # [ OPTIONAL ] [ DEFAULT gmail.com - set if other such as google apps domain ]
        SetCallBacks =>  {                             # [ OPTIONAL ]
                 message     =>  \&function ,
                 presence    =>  \&function ,
                 iq          =>  \&function ,
                 send        =>  \&function ,
                 receive     =>  \&function ,
                 update      =>  \&function ,
          }                                ,
        RESOURCE     => 'My Chat Prog'     ,           # [ OPTIONAL ]
    ) ;

send_message

This function sends a message to a contact. ( eg: $ob->send_message( $to, $message ) )

wait_for_message

This function waits for a message for a maximum of 10 sec ( or for the duration set by parameter ), returns the parsed message in a hash if there is one or undef it there is none.

The difference between this and wait_for_communication is that this will only return a chat message recieved and not other communications such as pings.

Pings recieved for presence of a buddy online are used to update the 'online_buddy' list ( see get_buddies below ).

wait_for_communication

This function waits for any kind of communication from GTalk for a maximum of 10 sec ( or for the duration set by parameter ), returns the raw xml of the message or undef if there is none.

presence_send

This function sends out a presence based on the last presence send timestamp. The presence ping sent to GTalk will show the authenticated user as 'online'.

It should be noted that wait_for_message, wait_for_communication and send_message all call this function and so calling it is explicitly not required unless those functions are not called for a significantly long time ( i.e. over 300 sec ).

This function takes no parameters by default but if called with any non zero value [ ex: $object->presence_send( 1 ) ] it will force send a presence request regardless of when the last one was sent.

get_buddies

This function gets a list of all chat contacts. The returned list is NOT a list of online buddies but that of all contacts.

get_online_buddies

This function returns a list of buddies for which we have presence information. This function does not use the inbuilt functions provided by NET::XMPP because, for some reason, they do not work.

This means that the longer you wait the better this list.

INTERNAL SUBROUTINES/METHODS

These functions are used by the module. They are not meant to be called directly using the Net::XMPP::Client::GTalk object although there is nothing stoping you from doing that.

_connect

This is an internal function and should not be used externally.

Used to connect to GTalk.

_receive_callback

This is an internal function and is not to be used externally.

This function is used to receive the contents of a message from GTalk.

_parse_communication

This is an internal function and is not to be used externally.

This function parses the XML recieved from GTalk.

_process_message_communication

This is an internal function and is not to be called externally.

It parses the message XML to return a hash while also updating the online buddy list.

_process_non_message_communication

This is an internal function and is not to be used externally.

It processes non-chat messages from GTalk.

_parse_from_expression

This is an internal function and should not be used externally.

It breaks the from field of a communication down into from and client.

_process_presence

This is an internal function and is not to be used externally.

This function adds a buddy to the online buddy list and removes buddies based on a timeout of 700 sec ( i.e. If there has been no presence from a particular buddy for over 700 sec )

DESTROY

Global Destructor.

This function closes the connection to Gtalk if Disconnect has not already been called.

AUTHOR

Harish Madabushi, <harish.tmh at gmail.com>

BUGS

Please report any bugs or feature requests to bug-net-xmpp-client-gtalk at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP-Client-GTalk. 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 Net::XMPP::Client::GTalk

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2013 Harish Madabushi.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.