WWW::Myspace::Message.3pm

Langue: en

Version: 2008-06-19 (debian - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

NAME

WWW::Myspace::Message - Auto-message your MySpace friends from Perl scripts

VERSION

Version 0.16

WARNING

March 2007: Using WWW::Myspace for commenting, messaging, or adding friends will probably get your Myspace account deleted or disabled.

SYNOPSIS

  use WWW::Myspace;
  use WWW::Myspace::Message;
  
  my $myspace = new WWW::Myspace;
  
  my $message = new WWW::Myspace::Message( $myspace );
  
  $message->subject("Hi there!");
  $message->message("I'm sending you a message!\nIsn't that cool?\n");
  $message->add_to_friends( 1 );
  $message->friend_ids( $myspace->get_friends );
  $message->send_message;
 
 

The above will send a message to all our myspace friends, stopping if it sends max_count messages or if it receives a CAPTCHA request. Running the same routine again will continue sending where it left off, so if you have a lot of friends you could run it from a cron job.

WWW::Myspace::Message lets you create a message and send it to a group of friends. It implements a counter to avoid tripping WWW::Myspace anti-spam features. If you want to circumvent anti-spam features, this is not the module for you.

EXAMPLES

Since you may have more than 300 people to message, the following script will send a message to all of your friends, and then reset the exclusions file. This allows it to run as a sort of daemon. It will run for days if necessary and stop when finished.

  use WWW::Myspace;
  use WWW::Myspace::Message;
 
  my $myspace = new WWW::Myspace;
 
  my $message = WWW::Myspace::Message->new( $myspace );
  $message->subject("Hi there!");
  $message->message("I'm sending you a message!\nIsn't that cool?\n");
  $message->friend_ids( $myspace->get_friends );
 
  my $response = "";
 
  # Send our message to our friends until we're done - may take
  # several days if we're popular.
  while ( $response ne "DONE" ) {
         # Send to as many as we can right now. Will stop either
         # because it's DONE, it was asked for a CAPTCHA response,
         # or because it maxed out the COUNTER.
         $response = $message->send_message;
 
         # Wait for a day. (You can probably wait for just 12 hours).
         sleep 24*60*60;
  }
 
  # We're done sending this message - reset the exclusions file
  # completely.
  $message->reset_exclusions;
 
 

Note that because of the log WWW::Myspace::Message keeps, either script could be interrupted and restarted without re-sending to anyone.

The ``while'' loop above can be replaced with the ``send_all'' convenience method:

  $message->send_all;
 
 

This is probably the most practical example:

  # Set up
  use WWW::Myspace;
  use WWW::Myspace::Message;
 
  my $myspace = new WWW::Myspace;
 
  # Create the message
  my $message = WWW::Myspace::Message->new( $myspace );
  $message->subject("Hi there!");
  $message->message("I'm sending you a message!\nIsn't that cool?\n");
  $message->friend_ids( $myspace->get_friends );
 
  # Send our message to our friends until we're done - may take
  # several days if we're popular.
  $message->send_all;
 
  # We're done sending this message - reset the exclusions file
  # completely.
  $message->reset_exclusions;
 
 

Again, you could kill and restart this script and it'd pick up where it left off (and even incorporiate any changes in your friend list!). Of course if it finished and you restarted it, it'd re-message everyone.

ACCESSOR METHODS

myspace

Sets/retreives the myspace object through which we'll send the message.

subject

Sets/retreives the subject of the message we're to post.

message

Sets/retrieves the message we're to post.

body

Convenience method, same as calling ``message''. ($message->body(``this is my message'') reads better sometimes).

add_to_friends

  $message->add_to_friends( 1 );
 
 

If called with 1 true value, HTML code for an ``Add to friends'' button will be added to the end of the message.

IMPORTANT NOTE: As of August, 2006 Myspace turns this code into a ``view profile'' code, which currently redirects until the browser locks up or reports an error. So, setting this to 1 will now display a ``View My Profile'' link at the end of the message instead of an ``Add to friends'' button.

skip_re

  $message->skip_re( 'i hate everybody!* ?(<br>)?' );
 
 

If set, is passed to the send_message method in Myspace.pm causing profiles that match the RE to be skipped. This failure is logged so the profile will not be attempted again, to prevent a huge list of failed profiles from forming and being retried over and over if you're running the script daily.

friend_ids

Sets/retreives the list of friend IDs to which we're going to send the message.
  $message->friend_ids( 12345, 12347, 123456 ); # Set the list of friends
  
  @friend_ids = $message->friend_ids; # Retreive the list of friends
 
 

cache_file

WWW::Myspace::Message keeps persistent track of which friends it's messaged to avoid duplicates even across multiple runs. It saves data about its messaging in the file specified in cache_file. Defaults to $myspace->cache_dir/messaged. cache_file will be created if it doesn't exist. If you specify a path, all directories in the path must exist (the module will not create directories for you).

max_count

Defaults to 100. This sets how many messages we'll post before pausing. This is mostly to avoid triggering overuse messages. (You're allowed about 360 per day (possibly per 12 hours period?)).

noisy

Defaults to 0 (not noisy). If set to 1, detailed progress will be output.

html

Defaults to 0. If set to 1, the ``noisy'' output will contain basic HTML tags so you can send the output to a web browser. Use this if you're displaying using a CGI script.

delay_time

Defaults to 24 hours (24*60*60). Specifies the amount of time to wait between sends when using the send_all method. If set to 0, send_all will return instead of sleeping. This is useful if you want to run a script daily from a crontab for example.

message_delay

Sets the delay between message sends. Defaults to 0, but you probably want to set this to something like 10.

random_delay

If set to 1, delays randomly between 3 seconds and the value of message_delay + 3. Defaults to 0.

paired_arguments

This method is used internally to define the -s and -m flags. If you subclass WWW::Myspace::Message, you can override this method to define more switches. The values of these are loaded into $self->{arguments}. i.e. $self->{arguments}->{'-s'} would give you the subject of the message.

METHODS

new( $myspace )

Initialze and return a new WWW::Myspace::Message object. $myspace is a WWW::Myspace object.

Example

use WWW::Myspace; use WWW::Myspace::Message;

my $myspace = new WWW::Myspace;

my $message = new WWW::Myspace::Message( $myspace );

exclusions

Returns a list of the friends we're not going to send the message to (because we already have). Returns the list in numerical order from lowest to highest. You probably only need this method for communicating with the user.

Example

( @already_messaged ) = $message->exclusions;

messaged

Returns a reference to a hash of friendIDs we've messaged and the status of the attempted messaging. Reads the data from the exclusions cache file if it hasn't already been read.

send_message

Send the message to the friends in the friend_ids list.

The send_message method will automatically skip all friendIDs in the ``exclusions'' list (see the exclusions method above). It will post until it has posted ``max_count'' successful posts, or until it receives a CAPTCHA request (``please enter the characters in the image above'').

As of version 0.14, send_message will check the Last Login date of the friend_id to which it's sending each message (using Myspace.pm's ``last_login'' method). If the Last Login is older than 60 days ago, the friendID will be skipped and ``FL'' will be logged. The friendID will be exluded from future runs to prevent future runs from re-checking a huge list of probably dead accounts.

send_message returns a status string indicating why it stopped:

  CAPTCHA if a CAPTCHA image code was requested.
  USAGE if we got a message saying we've exceeded our daily usage.
  COUNTER if it posted max_count comments and stopped.
  FAILURES if it keeps getting errors (more than 50 in a row).
  DONE if it posted everywhere it could.
 
 

send_all

This convenience method implements the while loop script example in the SYNOPSIS section above. If the response is ``DONE'', it exits. Otherwise, it sleeps for the number of seconds set in ``delay_time'' and calls send again. It repeats this until it receives ``DONE'' from the send method. send_all does NOT reset the exclusions file.

Returns the last response code received from send_message. This will always be ``DONE'' unless delay_time is set to 0 (which is redundant, but exists for scripting convenience as it allows users of your script to set delay_time to 0 if they want to control the messaging, without you having to call a different method - see message_group for example).

EXAMPLE
 use WWW::Myspace;
 use WWW::Myspace::Message;

  my $myspace = new WWW::Myspace;
  my $message = new WWW::Myspace::Message( $myspace );
 
  $message->subject("Hi there!");
  $message->message("This is a great message wraught with meaning.");
  $message->friend_ids( $myspace->get_friends );
  $message->send_all;
 
 

reset_exclusions

Resets the cache file (which contains previously messaged friendIDs that we'd exclude).

save( filename )

Saves the message to the file specified by ``filename''.

load( filename )

Loads a message in YAML format (i.e. as saved by the save method) from the file specified by filename.

AUTHOR

Grant Grueninger, "<grantg at cpan.org>"

BUGS

new method should probably accept a hash of arguments to set all accessable settings (i.e. cache_file). Should also be callable with no arguments.
If cache_file is called with no arguments and cache_file has not been set, it will create the cache dir by invoking the make_cache_dir method of the myspace object. It should probably not create the directory until it's actually writing to the file. Of course, if you don't set cache_file, the first time the method is called would be when writing to the cache file.
If the myspace object hasn't been passed to the WWW::Myspace::Message object yet, and cache_file is called to retreive the default cache_file, the method will croak (as it's trying to call $myspace->make_cache_dir).
If you somehow write to the exclusions file before the exclusions file has been read, $self->messaged will not read the exclusions cache file, and will therefore have an incomplete list. This shouldn't happen in normal operation as the send_message method reads the exclusions file when it's called.

Please report any bugs or feature requests to "bug-www-myspace at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Myspace>. 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 WWW::Myspace::Message
 
 

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/WWW-Myspace>

CPAN Ratings

<http://cpanratings.perl.org/d/WWW-Myspace>

RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Myspace>

Search CPAN

<http://search.cpan.org/dist/WWW-Myspace>

ACKNOWLEDGEMENTS

Copyright 2006 Grant Grueninger, all rights reserved.

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