NAME
WWW::Myspace - Access MySpace.com profile information from Perl
VERSION
Version 0.43
SYNOPSIS
WWW::Myspace.pm provides methods to access your myspace.com account and functions automatically. It provides a simple interface for scripts to log in, access lists of friends, scan user's profiles, retreive profile data, send messages, and post comments.
use WWW::Myspace;
my $myspace = WWW::Myspace->new ($account, $password);
OR
my $myspace = new WWW::Myspace; # Prompts for email and password
unless ( $myspace->logged_in ) { die "Login failed: " . $myspace->error }
my ( @friends ) = $myspace->get_friends();This module is designed to help you automate and centralize redundant tasks so that you can better handle keeping in personal touch with numerous friends or fans, or coordinate fan communications among multiple band members. This module operates well within MySpace's security measures. If you're looking for a spambot, this ain't it.
WWW::Myspace works by interacting with the site through a UserAgent object, using HTTP::Request::Form to process forms. Since by nature web sites are dynamic, if you find that some interaction with the site breaks, check for a new version of this module (or if you go source diving, submit a patch). You can run "cpan -i WWW::Myspace" as a cron job or before running your scripts, if appropriate, to make sure you have the latest version.
SET OPTIONS / LOG IN
The new method takes the following options, all of which are optional. See the accessor methods below for defaults. Any option can be passed in a hash or hashref to the "new" method, and retreived or set using the appropriate accessor method below.
account_name => 'myaccount',
password => 'mypass',
cache_dir => '/path/to/dir',
cache_file => 'filename', # $cache_dir/$cache_file
auto_login => 1 # 1 or 0, default is 1.OPTION ACCESSORS
These methods can be used to set/retreive the respective option's value. They're also up top here to document the option, which can be passed directly to the "new" method.
account_name
Sets or returns the account name (email address) under which you're logged in. Note that the account name is retreived from the user or from your program depending on how you called the "new" method. You'll probably only use this accessor method to get account_name.
EXAMPLE
The following would prompt the user for their login information, then print out the account name:
use WWW::Myspace;
my $myspace = new WWW::Myspace;
print $myspace->account_name;
$myspace->account_name( 'other_account@myspace.com' );
$myspace->password( 'other_accounts_password' );
$myspace->site_login;WARNING: If you do change account_name, make sure you change password and call site_login. Changing account_name doesn't (currently) log you out, nor does it clear "password". If you change this and don't log in under the new account, it'll just have the wrong value, which will probably be ignored, but who knows.
password
Sets or returns the password you used, or will use, to log in. See the warning under "account_name" above - same applies here.
cache_dir
WWW::Myspace stores the last account/password used in a cache file for convenience if the user's entering it. Other modules store other cache data as well.
cache_dir sets or returns the directory in which we should store cache data. Defaults to $ENV{'HOME'}/.www-myspace.
If using this from a CGI script, you will need to provide the account and password in the "new" method call, or call "new" with "auto_login => 0" so cache_dir will not be used.
cache_file
Sets or returns the name of the file into which the login cache data is stored. Defaults to login_cache.
If using this from a CGI script, you will need to provide the account and password in the "new" method call, so cache_file will not be used.
auto_login
Really only useful as an option passed to the "new" method when creating a new WWW::Myspace object.
# Don't log in, just create a new object
my $myspace = new WWW::Myspace( auto_login => 0 );
Defaults to 1 for backwards compatibility.
new( $account, $password )
new( )
If called without the optional account and password, the new method looks in a user-specific preferences file in the user's home directory for the last-used account and password. It prompts for the username and password with which to log in, providing the last-used data (from the preferences file) as defaults.
Once the account and password have been retreived, the new method automatically invokes the "site_login" method and returns a new WWW::Myspace object reference. The new object already contains the content of the user's "home" page, the user's friend ID, and a UserAgent object used internally as the "browser" that is used by all methods in the WWW::Myspace class.
Myspace.pm is now a subclass of WWW::Myspace::MyBase (I couldn't resist, sorry), which basically just means you can call new in many ways:
EXAMPLES
use WWW::Myspace;
# Prompt for username and password
my $myspace = new WWW::Myspace;
# Pass just username and password
my $myspace = new WWW::Myspace( 'my@email.com', 'mypass' );
# Pass options as a hashref
my $myspace = new WWW::Myspace( {
username => 'my@email.com',
password => 'mypass',
cache_file => 'passcache',
} );
# Hash
my $myspace = new WWW::Myspace(
username => 'my@email.com',
password => 'mypass',
cache_file => 'passcache',
auto_login => 0,
);
# Print my friend ID
print $myspace->my_friend_id;
# Print the contents of the home page
print $myspace->current_page->content;
# Print all my friends with a link to their profile.
@friend_ids = $myspace->get_friends;
foreach $id ( @friend_ids ) {
print 'http://profile.myspace.com/index.cfm?'.
'fuseaction=user.viewprofile&friendID='.
${id}."\n";
}
# How many friends do we have? (Note: we don't include Tom
# because he's everybody's friend and we don't want to be
# bugging him with comments and such).
print @friend_ids . " friends (not incl Tom)\n";site_login
Logs into the myspace account identified by the "account_name" and "password" options. You don't need to call this right now, because "new" does it for you. BUT I PLAN TO CHANGE THAT. You don't need to be logged in to access certain functions, so it's semi-silly to make you log in the second you call "new". Plus, it's not good practice to have "new" require stuff. Bad me.
So for now this is only useful to you if you find yourself logged out for some reason and want to log back in without making a new WWW::Myspace object. It's more useful for me though.
logout
Clears the current web browsing object and resets any login-specific internal values. Currently this drops and creates a new WWW::Mechanize object. This may change in the future to actually clicking "logout" or something.
CHECK STATUS
logged_in
Returns true if login was successful. When you call the new method of WWW::Myspace, the class logs in using the username and password you provided (or that it prompted for). It then retreives your "home" page (the one you see when you click the "Home" button on myspace.com, and checks it against an RE. If the page matches the RE, logged_in is set to a true value. Otherwise it's set to a false value.
Notes:
- This method is only set on login. If you're logged out somehow,
this method won't tell you that (yet - I may add that later).
- The internal login method calls this method to set the value.
You can (currently) call logged_in with a value, and it'll set
it, but that would be stupid, and it might not work later
anyway, so don't.
Examples:
my $myspace = new WWW::Myspace;
unless ( $myspace->logged_in ) {
die "Login failed\n";
}
# This will try forever to log in
my $myspace;
do {
$myspace = new WWW::Myspace( $username, $password );
} until ( $myspace->logged_in );error
This value is set by some methods to return an error message. If there's no error, it returns a false value, so you can do this:
$myspace->get_profile( 12345 );
if ( $myspace->error ) {
warn $myspace->error . "\n";
} else {
# Do stuff
}current_page
Returns a reference to an HTTP::Response object that contains the last page retreived by the WWW::Myspace object. All methods (i.e. get_page, post_comment, get_profile, etc) set this value.
EXAMPLE
The following will print the content of the user's profile page:
use WWW::Myspace;
my $myspace = new WWW::Myspace;
print $myspace->current_page->content;mech
The internal WWW::Mechanize object. Use at your own risk: I don't promose this method will stay here or work the same in the future. The internal methods used to access Myspace are subject to change at any time, including using something different than WWW::Mechanize.
GET INFO
my_friend_id
Returns the friendID of the user you're logged in as. Croaks if you're not logged in.
EXAMPLE
print $myspace->my_friend_id;is_band( [friend_id] )
Returns true if friend_id is a band profile. If friend_id isn't passed, returns true if the account you're logged in under is a band account. If it can't get the profile page it returns -1 and you can check $myspace->error for the reason (returns a printable message). This is used by send_friend_request to not send friend requests to people who don't accept them from bands, as myspace passively accepts the friend request without displaying an error, but doesn't add the friend request.
EXAMPLE
$myspace->is_band( $friend_id );
if ( $myspace->error ) {
die $myspace->error . "\n";
} else {
print "They're a band, go listen to them!\n";
}user_name
Returns the profile name of the logged in account. This is the name that shows up at the top of your profile page above your picture. This is NOT the account name.
Normally you'll only retreive the value with this method. When logging in, the internal login method calls this routine with the contents of the profile page and this method extracts the user_name from the page code. You can, if you really need to, call user_name with the contents of a page to have it extract the user_name from it. This may not be supported in the future, so it's not recommended.
friend_user_name( friend_id )
Returns the profile name of the friend specified by friend_id. This is the name that shows up at the top of their profile page above their picture. (Note, DON'T go using this to sign comments because most users use funky names and it'll just look cheesy. If you really want to personalize things, write a table mapping friend IDs to first names - you'll have to enter them yourself).
friend_url( friend_id )
Returns the custom URL of friend_id's profile page. If they haven't specified one, it returns an empty string.
Example:
foreach my $friend_id ( $myspace->get_friends ) {
my $url = $myspace->friend_url( $friend_id );
if ( $url ) {
print 'Friend's custom URL: http://www.myspace.com/' .
$myspace->friend_url( $friend_id );
} else {
print 'Friend doesn't have a custom URL. Use: '.
'http://www.myspace.com/' . $friend_id;
}
}friend_count
Returns the logged in user's friend count as displayed on the profile page ("You have NN friends").
Note that due to one of WWW::Myspace's many bugs, this count may not be equal to the count of friends returned by get_friends.
Like the user_name method, friend_count is called by the internal login method with the contents of the user's profile page, from which it extracts the friend count using a regexp on the "You have NN friends" string. If you need to, you can do so also, but again this might not be supported in the future so do so at your own risk.
get_profile( $friend_id )
Gets the profile identified by $friend_id.
Returns a reference to a HTTP::Response object that contains the profile page for $friend_id.
The following displays the HTML source code of the friend's
profile identified by "$friend_id":
my $res = $myspace->get_profile( $friend_id );
print $res->content;FIND PEOPLE
cool_new_people( $country_code )
This method provides you with a list of "cool new people". Currently Myspace saves the "cool new people" data to a JavaScript file which is named something like this:
http://viewmorepics.myspace.com/js/coolNewPeople_us.js
Since these files are named using country codes, you'll need to provide the ISO 3166-1 two letter code country code for the list you'd like to get. For example,
$myspace->cool_new_people( 'US' )When called in a list context, this function returns the friend ids of the cool folks:
my @friend_ids = $myspace->cool_new_people( 'US' );If you treat the return value as a hash reference, you'll get a hash keyed on friend ids. The values consist of hash references containing the urls of the friend thumbnails (thumb_url) as well as their display names (friend_user_name). There will probably be about 200 keys returned in the hash.
my $cool = $myspace->cool_new_people('US');
my %cool_new_people = %{$cool};
%cool_new_people = {
...
'friend_id' => {
'thumb_url' => 'url_to_jpg_here',
'friend_user_name' => 'friend display name here'
},
...
}So far, we know of 4 country-specific cool new people lists: AU, CA, UK/GB and US Submitting any of these values to the function should return valid friend ids. If you want to check for other countries for which cool people lists may exist, you can do something like this:
use Locale::SubCountry;
my $world = new Locale::SubCountry::World;
my %countries = $world->code_full_name_hash();
my @country_codes = sort keys %countries;
foreach my $country_code ( @country_codes ) {
my %cool_people = $myspace->cool_new_people($country_code);
if (%cool_people) {
print "$country_code $countries{$country_code} has cool folks\n";
}
else {
print "****** $country_code\n";
}
}
get_friends
Returns, as a list of friendIDs, all of your friends. It does not include Tom, because he's everybody's friend and when you're debugging your band central CGI page it's probably best to limit your mistakes to actual friends.
@friends = $myspace->get_friends;As of version 0.37, get_friends is context sensitive and returns additional information about each friend if called in a hashref context. Currently the only information is the page number on which the friend was found. This is handy if, say, you have a lot of friends and you want to add one to your top 8 but you don't know what page they're on.
# Find a friend lost in your friends list
$lost_friend=12345;
$friends = $myspace->get_friends;
print "Found friend $lost_friend on page " .
$friends->{"$lost_friend"}->{page_no} . "!\n";Myspace trivia: The friends on friends lists are sorted by friendID.
Croaks if called with no arguments (i.e. to get your friends) and you're not logged in.
friends_from_profile( friend_id )
Returns a list of the friends of the profile specified by friend_id. If passed a list of friend IDs, scans each profile and returns a sorted, unique list of friendIDs. Yes, that means if you pass 5 friendIDs and they have friends in common, you'll only get each friendID once. You're welcome.
Examples:
# Band 12345 and 54366 sound like us, get their friends list
@similar_bands_friends=$myspace->friends_from_profile( 12345, 54366 );
# a further example
# before you do anything with these
# ids, make sure you don't already
# have them as friends:
use List::Compare;
my @current_friends = $myspace->get_friends;
my @potential_friends = $myspace->friends_from_profile( 12345, 54366 );
my $lc = List::Compare->new(
{ lists =>
[\@current_friends, \@potential_friends],
accelerated => 1
} );
my @unique_ids = $lc->get_complement;friends_in_group( group_id )
Returns a list of the friend IDs of all people in the group identified by group_id. Tom is disincluded as in get_friends (because the same routine is used to get the friendIDs).
Example:
my @hilary_fans = $myspace->friends_in_group( 100011592 );
@hilary_fans now contains the friendID of everyone in the HIlary
Duff Fan Club group (group ID 100011592 ).
To get the group ID, go to the group page in WWW::Myspace and look at the URL: http://groups.myspace.com/index.cfm?fuseaction=groups.viewMembers&GroupID=100011592&adTopicId=&page=3
The group ID is the number after "GroupID=".
friends_who_emailed
Returns, as a list of friend IDs, all friends with messages in your inbox (mail). Note that this only tells you who you have mail from, not how many messages, nor does it contain any method to link to those messages. This is primarily designed to aid in auto-responding programs that want to not contact (comment or email) people who have sent messages so someone can attend to them personally. This routine also disincludes Tom, mainly because it uses the same routine as "get_friends". Croaks if you're not logged in.
@friends = $myspace->friends_who_emailed;search_music
Search for bands using the search music form.
Takes a hashref containing field => value pairs that are passed directly to submit_form to set the search criteria.
http://musicsearch.myspace.com/index.cfm?fuseaction=music.searchThe easiest way I've found to get your values is to fill them in on the search form, click "Update", then look at the page source. Scroll to the botton where "PageForm" is and you'll see the values you selected. Put the pertinent ones (i.e. things you changed) into your script. Note that the field *names* are different, so just take the values, and use the names as described below.
Any value the form can take (present or future) can be passed, so in theory you could write a CGI front-end also that just had the form, posted the values to itself, then used those values to call this method (i.e. do what I suggested above automatically).
Here are the currently available form labels/values (looking at the form helps):
genreID: See the form for values
search_term:
0: Band Name
1: Band Bio
2: Band Members
3: Influences
4: Sounds like
keywords: text field. Use it if you're searching by band name, etc.
Country: Labeled "Location" in the form. See the form source for values.
localType: The radio buttons. Set to:
countryState: To search by Country / State
distanceZip: To search by distance and zip code.
if localType is "countryState", set this:
state: State code (like the post office uses, thankfully. See form code
if you have any questions).
If localType is "distanceZip", set these:
zip: The 5-digit zip code.
distance: Distance from zip code [0|5|10|20|50|100|500]. 0="Any" and is the
default.
OrderBy: [ 5 = Plays | 4 = Friends |3 = New | 2 = Alphabetical ]
Default is 2.IMPORTANT: Results are currently sorted by friendID regardless of the OrderBy setting.
For those who care about details, here's how the Search Music page works:
There are three forms on the page, the generic "search" form in the nav bar, a second form called "myForm" that is the user-modified update form, and a third form called "PageForm" that is actually used to pass the values. PageForm is updated with the values after "update" is clicked in myForm. Clicking "Next" just sets (using JavaScript in Myspace) the page value in PageForm and submits PageForm. Oddly enough, PageForm ends up being a "GET", so you could theoretically just loop through using URLs. But we don't, we fill in the form like a browser would.
CONTACT PEOPLE
These methods interact with other users.
post_comment( $friend_id, $message )
Post $message as a comment for the friend identified by $friend_id. The routine confirms success or failure by reading the resulting page. It returns a status string as follows:
P => 'Passed! Verification string received.'
PA => 'Passed, requires approval.'
FF => 'Failed, you must be someone\'s friend to post a comment about them.'
FN => 'Failed, network error (couldn\'t get the page, etc).'
FC => 'Failed, CAPTCHA response requested.'
F => 'Failed, verification string not found on page after posting.'Warning: It is possible for the status code to return a false "Failed" if the form post is successful but the resulting page fails to load.
If called in scalar context, it returns the status code. If called in list context, returns the status code and the description.
EXAMPLE: use WWW::Myspace; my $myspace = new WWW::Myspace;
foreach $id ( $myspace->friends_who_emailed ) {
$status = $myspace->post_comment( $id, "Thanks for the message!" )
}
# Get a printable status (and print it)
( $status, $desc ) = $myspace->post_comment(
$id, "Thanks for being my friend!"
);
print "Status of post: $desc\n";If called when you're not logged in, post_comment croaks to make you look stupid.
See also the WWW::Myspace::Comment module that installs with the distribution.
captcha
If post_comment returns "FC", the "captcha" method will return the URL to the CAPTCHA image that contains the text that the user must enter to post the comment.
Psuedo-code example of how you can use this in a CGI script:
my $response = $myspace->post_comment( 12345, 'This is a message' );
if ( $response eq 'FC' ) {
# Get and display the image
print '<form>\n'.
"<img src='" . $myspace->captcha . "'>\n".
'<input type=text name=\'CAPTCHAResponse\'>' .
'<input type=submit>' .
'</form>';
}
# Post the comment
$myspace->post_comment( 12345, 'This is a message', $captcha_response );
(Use in a CGI script is currently problematic since you'll lose the
Myspace object. I'll try to write a better example later. You could
try doing a YAML Dump and Load of the $myspace object...)comment_friends( $message )
comment_friends( $message, { 'ignore_dup' => 1 } )
This convenience method sends the message in $message to all of your friends. (Since you can only comment friends, it sends the comment to everyone you can).
By default it will scan the user's profile page for a previous comment (by searching for your profile URL on the page, which also detects you if you're in their top 8 or otherwise linked to from their page).
If called in the second form, it forgoes this duplicate checking (ignores duplicates), and posts anyway.
Note that you'll probably want to use the WWW::Myspace::Comment module as if the process is interrupted (which is likely), this routine doesn't offer a way to recover. The WWW::Myspace::Comment module logs where comments have been left, scans for previous comments we've left on the user's page, and can stop after a specified number of posts to avoid triggering security measures. It can also be re-run without leaving duplicate comments.
Of course, if you just want to whip off a quick comment to a few (less than 50) friends, this method's for you.
EXAMPLE: A simple script to leave a comment saying "Merry Christmas" to everyone on your friends list:
use WWW::Myspace;
my $myspace = new WWW::Myspace;
$myspace->comment_friends( "Merry Christmas!" );already_commented
Returns true if there is a link to our profile on "$friend_id"'s page. (If we've left a comment, there'll be a link).
Note that if you're friends with this person and they have another link to your profile on their page, this will return true, even though you may not have left a comment.
EXAMPLE
my WWW::Myspace;
my $myspace = new WWW::Myspace;
foreach $friend_id ( $myspace->get_friends ) {
unless ( $myspace->already_commented( $friend_id ) ) {
$myspace->post_comment(
$friend_id,
"Hi, I haven't commented you before!"
)
}
}already_commented croaks if called when you're not logged in.
inbox
Returns a reference to an array of hash references that contain data about the messages in your Myspace message inbox. The hashes contain:
sender (friendID)
status (Read, Unread, Sent, Replied)
message_id (The unique ID of the message)
subject (The subject of the message)The messages are returned IN ORDER with the newest first to oldest last (that is, the same order in which they'd appear if you were looking through your inbox).
I'm sure reading that first line made you as dizzy as it made me typing it. I think this says it all much more clearly:
EXAMPLE
# This script displays the contents of your inbox.
use WWW::Myspace;
$myspace = new WWW::Myspace;
print "Getting inbox...\n";
my $messages = $myspace->inbox;
# Display data for each message
foreach $message ( @{$messages} ) {
print "Sender: " . $message->{sender} . "\n";
print "Status: " . $message->{status} . "\n";
print "messageID: " . $message->{message_id} . "\n";
print "Subject: " . $message->{subject} . "\n\n";
}(This script is in the sample_scripts directory, named "get_inbox").
"inbox" croaks if called when you're not logged in.
read_message( message_id )
Returns a hashref containing the message identified by message_id.
my $message_ref = $myspace->read_message( 123456 );
print 'From: ' . $message_ref->{'from'} . .'\n' . # Friend ID of sender
'Date: ' . $message_ref->{'date'} . .'\n' . # Date (as formatted on Myspace)
'Subject: ' . $message_ref->{'subject'} .'\n' .
'Body: ' . $message_ref->{'body'} . '\n'; # Message bodyCroaks if you're not logged in.
reply_message( $message_id, $reply_message )
Warning: This is a new, un-tested method. If you're reading this, it means I had to release a new version for some reason before I got to complete the testing and documentation of this method. It "should" work fine. Let me know if it does or not.
Reply to message $message_id using the text in the string $reply_message.
Returns a status code:
P: Posted. Verified by HTTP response code and reading a regexp
from the resulting page saying the message was sent.
FC: Failed. A CAPTCHA response was requested.
FF: Failed. The person's profile is set to private. You must
be their friend to message them.
FA: Failed. The person has set their status to "away".
FE: Failed. The account has exceeded its daily usage.
FN: Failed. The POST returned an unsuccessful HTTP response code.
F: Failed. Post went through, but we didn't see the regexp on the
resulting page (message may or may not have been sent).
Example:
my $status = $myspace->reply_message( 1234567, "Thanks for emailing me!" );If you're not logged in? Croaks.
send_message( $friend_id, $subject, $message, $add_friend_button )
Send a message to the user identified by $friend_id. If $add_friend_button is a true value, HTML code for the "Add to friends" button will be added at the end of the message.
$status = $myspace->send_message( 6221, 'Hi Tom!', 'Just saying hi!', 0 );
if ( $status eq "P" ) { print "Sent!\n" } else { print "Oops\n" }
Returns a status code:
P => Passed! Verification string received.
FF => Failed, profile set to private. You must be their
friend to message them.
FN => Failed, network error (couldn\'t get the page, etc).
FA => Failed, this person\s status is set to "away".
FE => Failed, you have exceeded your daily usage.
FC => Failed, CAPTCHA response requested.
F => Failed, verification string not found on page after posting.If called in list context, returns the status code and text description.
( $status, $desc ) = $myspace->send_message( $friend_id, $subject, $message );
print $desc . "\n";See also WWW::Myspace::Message, which installs along with the distribution.
(Croaks if called when you're not logged in).
delete_message( @message_ids )
Deletes the message(s) identified by @message_ids. Takes a list of messageIDs or of hashrefs with a message_id subcomponent (such as one gets from the "inbox" method). Croaks if called when not logged in.
Deletes all messages in a single post. Returns true if it worked, false if not, and sets the "error" method to the error encountered.
Example:
# Delete message 12345
$myspace->delete_message( 12345 );
# File myspace mail where it belongs.
$all_messages = $myspace->inbox;
$myspace->delete_message( @{ $messages } ); approve_friend_requests( [message] )
Looks for any new friend requests and approves them. Returns a list of friendIDs that were approved. If "message" is given, it will be posted as a comment to the new friend. If called when you're not logged in, approve_friend_requests will croak.
If approve_friend_requests runs into a CAPTCHA response when posting comments, it will set $myspace->captcha to the URL of the CAPTCHA image. If no CAPTCHA was encountered, $myspace->captcha will be 0. So you can say:
if ( $myspace->captcha ) { print "oh no!\n" }approve_friend_requests will approve all friends wether or not it can comment them as it approves first, then comments the list of approved friends.
EXAMPLES
# Approve any friend requests
@friends_added = $myspace->approve_friend_requests;
# Print the number of friends added and their friend IDs.
print "Added " . @friends_added . " friends: @friends_added.";
# Approve new frieds and leave them a thank you comment.
@friends_added = $myspace->approve_friend_requests(
"Thanks for adding me!\n\n- Your nww friend" );Run it as a cron job. :)
Note that "\n" is properly handled if you pass it literally also (i.e. from the command line). That is if you write this "approve_friends" script:
#!/usr/bin/perl -w
# usage: approve_friends [ "message" ]
use WWW::Myspace;
my $myspace = new WWW::Myspace;
$myspace->approve_friend_requests( @ARGV );
And run it as:
approve_friends "Thanks for adding me\!\!\n\n- Me"
You'll get newlines and not "\n" in the message. There, I even gave you your script.
send_friend_request( $friend_id )
IMPORTANT: THIS METHOD'S BEHAVIOR HAS CHANGED SINCE VERSION 0.25!
Sorry, I hate to break backwards-compatibility, but to keep this method in line with the rest, I had to. The changes are: 1) It takes only one friend, it will DIE if you give it more (mainly to let you know that #2 has changed so your scripts don't think they're succeeding when they're not). 2) It no longer returns pass/fail, it returns a status code like post_comment.
Send a friend request to the friend identified by $friend_id. Croaks if not logged in.
This is the same as going to their profile page and clicking the "add as friend" button and confirming that you want to add them.
Returns a status code and a human-readable error message:
FF: Failed, this person is already your friend.
FN: Failed, network error (couldn't get the page, etc).
FP: Failed, you already have a pending friend request for this person
FC: Failed, CAPTCHA response requested.
P: Passed! Verification string received.
F: Failed, verification string not found on page after posting.After send_friend_request posts a friend request, it searches for various Regular Expressions on the resulting page and sets the status code accordingly. The "F" response is of particular interest because it means that the request went through fine, but none of the known failure messages were received, but the verification message wasn't seen either. This means it -might- have gone through, but probably not. Of course, worst case here is you try again.
EXAMPLES
# Send a friend request and get the response
my $status = $myspace->send_friend_request( 12345 );
# Send a friend request and print the result
my ( $status, $desc ) = $myspace->send_friend_request( 12345 );
print "Received code $status: $desc\n";
# Send a friend request and check for some status responses.
my $status = $myspace->send_friend_request( 12345 );
if ( $status =~ /^P/ ) {
print "Friend request sent\n";
} else {
if ( $status eq 'FF' ) {
print "This person is already your friend\n";
} elsif ( $status eq 'FC' ) {
print "Received CAPTCHA image request\n";
}
}
# Send a bunch of friend requests
my @posted = ();
my @failed = ();
foreach my $friend ( @friends ) {
print "Posting to $friend: ";
my $status = $myspace->send_friend_request( $friend )
if ( $status =~ /^P/ ) {
print "Succeeded\n";
push ( @posted, $friend );
} else {
print "Failed with code $status\n";
push ( @failed, $friend );
}
# Stop if we got a CAPTCHA request.
last if $status eq 'FC';
}
# Do what you want with @posted and @failed.
Also see the WWW::Myspace::FriendAdder module, which adds multiple friends and lets you enter CAPTCHA codes.
send_friend_requests( @friend_ids )
Send friend requests to multiple friends. Stops if it hits a CAPTCHA request. Doesn't currently give any indication of which requests succeeded or failed. Use the code example above for that. Croaks if you're not logged in.
add_to_friends
Convenience method - same as send_friend_request. This method's here because the button on Myspace's site that the method emulates is usually labeled "Add to Friends".
add_as_friend
Convenience method - same as send_friend_request. This method's here Solely for backwards compatibility. Use add_to_friends or send_friend_request in new code.
delete_friend( @friend_ids )
Deletes the list of friend_ids passed from your list of friends.
$myspace->delete_friend( 12345, 151133 );Returns true if it posted ok, false if it didn't. Croaks if you're not logged in.
CORE INTERNAL METHODS
These are methods used internally to maintain or handle basic stuff (page retreival, error handling, cache file handling, etc) that you probably won't need to use (and probably shouldn't use unless you're submitting a code patch :).
get_page( $url, [ $regexp ] )
get_page returns a referece to a HTTP::Response object that contains the web page specified by $url.
Use this method if you need to get a page that's not available via some other method. You could include the URL to a picture page for example then search that page for friendIDs using get_friends_on_page.
get_page will try up to 20 times until it gets the page, with a 2-second delay between attempts. It checks for invalid HTTP response codes, and known Myspace error pages. If called with the optional regexp, it will consider the page an error unless the page content matches the regexp. This is designed to get past network problems and such.
EXAMPLE
The following displays the HTML source of MySpace.com's home
page.
my $res=get_page( "http://www.myspace.com/" );
print $res->content;_cache_page( $url, $res )
Stores $res in a cache.
_read_cache( $url )
Check the cache for this page.
_clean_cache
Cleans any non-"fresh" page from the cache.
_check_login
Checks for "You bust be logged in to do that". If found, tries to log in again and returns 0, otherwise returns 1.
submit_form( $url, $form_no, $button, $fields_ref, [ $regexp1 ], [ $regexp2 ] )
This format is being deprecated. Please use the format below if you use this method (which you shouldn't need unless you're writing more methods). Be aware that I might make this method private at some point.
submit_form( $options_hashref )
Valid options:
$myspace->submit_form( {
page => "http://some.url.org/formpage.html",
form_no => 1,
form_name => "myform", # Use this OR form_no...
button => "mybutton",
no_click => 0, # 0 or 1.
fields_ref => { field => 'value', field2 => 'value' },
re1 => 'something unique.?about this[ \t\n]+page',
re2 => 'something unique about the submitted page',
action => 'http://some.url.org/newpostpage.cgi', # Only needed in weird occasions
} );This powerful little method reads the web page specified by "page", finds the form specified by "form_no" or "form_name", fills in the values specified in "fields_ref", and clicks the button named "button".
You may or may not need this method - it's used internally by any method that needs to fill in and post a form. I made it public just in case you need to fill in and post a form that's not handled by another method (in which case, see CONTRIBUTING below :).
"page" can either be a text string that is a URL or a reference to an HTTP::Response object that contains the source of the page that contains the form. If it is an empty string or not specified, the current page ( $myspace->current_page ) is used.
"form_no" is used to numerically identify the form on the page. It's a simple counter starting from 0. If there are 3 forms on the page and you want to fill in and submit the second form, set "form_no => 1". For the first form, use "form_no => 0".
"form_name" is used to indentify the form by name. In actuality, submit_form simply uses "form_name" to iterate through the forms and sets "form_no" for you.
"button" is the name of the button to submit. This will frequently be "submit", but if they've named the button something clever like "Submit22" (as MySpace did in their login form), then you may have to use that. If no button is specified (either by button => '' or by not specifying button at all), the first button on the form is clicked.
If "no_click" is set to 1, the form willl be submitted without clicking any button. This is used to simulate the JavaScript form submits Myspace does on the browse pages.
"fields_ref" is a reference to a hash that contains field names and values you want to fill in on the form.
"re1" is an optional Regular Expression that will be used to make sure the proper form page has been loaded. The page content will be matched to the RE, and will be treated as an error page and retried until it matches. See get_page for more info.
"re2" is an optional RE that will me used to make sure that the post was successful. USE THIS CAREFULLY! If your RE breaks, you could end up repeatedly posting a form. This is used by post_comemnts to make sure that the Verify Comment page is actually shown.
"action" is the post action for the form, as in:
<form action="http://www.mysite.com/process.cgi">This is here because Myspace likes to do weird things like reset form actions with Javascript then post them without clicking form buttons.
EXAMPLE
This is how post_comment actually posts the comment:
# Submit the comment to $friend_id's page
$self->submit_form( "${VIEW_COMMENT_FORM}${friend_id}", 1, "submit",
{ 'f_comments' => "$message" }, '', 'f_comments'
);
# Confirm it
$self->submit_form( "", 1, "submit", {} );_add_to_form
Internal method to add a hidden field to a form. HTML::Form thinks we don't want to change hidden fields, and if a hidden field has no value, it won't even create an input object for it. If that's way over your head don't worry, it just means we're fixing things with this method, ad submit_form will call this method for you if you pass it a field that doesn't show up on the form.
Returns a form object that is the old form with the new field in it.
# Add field $fieldname to form $form (a HTML::Form object) and
# set it's value to $value.
$self->_add_to_form( $form, $fieldname, $value )get_friends_on_page( $friends_page );
This routine takes the SOURCE CODE of an HTML page and returns a list of friendIDs for which there are profile links on the page. This routine is used internally by "get_friends" to scan each of the user's "View my friends" pages.
Notes: - It does not return our friendID. - friendIDs are filtered so they are unique (i.e. no duplicates). - We filter out 6221, Tom's ID.
EXAMPLE:
List the friendIDs mentioned on Tom's profile:
use WWW::Myspace;
my $myspace = new WWW::Myspace;
$res = $myspace->get_profile( 6221 );
@friends = $myspace->get_friends_on_page( $res->content );
print "These people have left comments or have links on Tom's page:\n";
foreach $id ( @friends ) {
print "$id\n";
}remove_cache
Remove the login cache file. Call this after creating the object if you don't want the login data stored:
my $myspace = new WWW::Myspace( qw( myaccount, mypassword ) );
$myspace->remove_cache;make_cache_dir
Creates the cache directory in cache_dir. Only creates the top-level directory, croaks if it can't create it.
$myspace->cache_dir("/path/to/dir");
$myspace->make_cache_dir;This function mainly exists for the internal login method to use, and for related sub-modules that store their cache files by default in WWW:Myspace's cache directory.
_next_button
Takes the source code of a page, or nothing. If nothing is passed, uses $self->current_page->content.
Returns true if there is a next button on the page. This is so we can say:
last unless ( $self->_next_button( $page_source ) );
or:
while ( $self->_next_button ) { do stuff }
or
while ( $self->_next_button ) { do stuff and click next }One of these days I'm going write a "stuff" subroutine so I can actually type that.
EXAMPLES
IN PROGRESS
Methods that aren't quite working yet.
browse
XXX - NOT YET FUNCTIONAL
XXX - More debugging needs to be done to ensure accurate results, and tests need to be added to the test suite for it.
And now back to your normal docs:
Call browse with a hashref of your search criteria and it returns a list of friendIDs that match your criteria.
my @friends = $myspace->browse( {
'zipCode' => '91000',
'zipRadius' => '20',
'Gender' => 'genderWomen', # Pick one of these
'Gender' => 'genderMen',
'Gender' => 'genderBoth'
} );I'm not sure how I'm going to make the criteria passing easier. I'm also concerned about your script breaking if they change the browse form variable names. So maybe I'll add a mapping later.
For now, you have to look at the code for the browse page:
http://browseusers.myspace.com/browse/Browse.aspxSwitch to Advanced more and get the form variables and possible values from there.
Note that depending on any defaults is dangerous, as this is a strange form indeed.
_browse_next( $page )
The browse form's Next button calls a JavaScript function that sets "action" and "page" in the browse form and "clicks" submit. So we do the same here. Called by browse to simulate clicking "next".
_browse_action( $function_name )
Gets the action set by the specificied function on the Browse page.
AUTHOR
Grant Grueninger, <grantg at cpan.org>
Thanks to:
Tom Kerswill (http://tomkerswill.co.uk) for the friend_url method, which also inspired the friend_user_name method.
Olaf Alders (http://www.wundersolutions.com) for the human-readable status codes in send_friend request, for the excellent sample code which provides a workaround for CAPTCHA responses, and for the friends_from_profile idea.
KNOWN ISSUES
- -
-
delete_friend will probably only delete the first friendID passed.
- -
-
Some myspace error pages are not accounted for, such as their new Server Application error page. If you know enough about web development to identify an error page that would return a successful HTTP response code (i.e. returns 200 OK), but then displays an error message, please keep an eye out for such pages. If you get such an error message page, PLEASE EMAIL ME (see BUGS below) the page content so I can account for it.
- -
-
post_comment dies if it is told to post to a friendID that is not a friend of the logged-in user. (MySpace displays an error instead of a form). (may be fixed, 0.39).
- -
-
If the text used to verify that the profile page has been loaded changes in the future, get_profile and post_comments will report that the page hasn't been loaded when in fact it has.
- -
-
Something (probably UserAgent getting bad cookie data) is generating the following warnings when logging in: Day too big - 2238936 > 24855 Sec too big - 2238936 > 11647 Day too big - 2238936 > 24855 Sec too big - 2238936 > 11647
These are annoying but don't seem to affect the module.
- -
-
If an invalid username/password is given, the module will attempt to log in 20 times, displaying 'Got "Not logged in" page', then exit with $self->error set to "Not logged in". It really should check for an invalid login and return an appropriate error.
TODO
Have 'approve_friends' method check GUIDS after first submit to make sure the current page of GUIDS doesn't contain any duplicates. This is to prevent a possible infinite loop that could occur if the submission of the friend requests fails, and also to signal a warning if myspace changes in a way that breaks the method.
Add checks to all methods to self-diagnose to detect changes in myspace site that break this module.
Add methods to FriendAdder.pm to: 1-exlude friends, 2-exclude pending friends, 3-cache like Comment.pm, 4-exclude friends in the "messaged" cache file.
get_friends needs to throw an error, or at least set error, if it can't return the full list of friends (i.e. if either of the "warn" statements are triggered)
Review and possibly rework code to properly use (, abuse, or replace) WWW::Mechanize.
See: - delete_friends - "proper" forced handling of a passed form.CONTRIBUTING
If you would like to contribute to this module, you can email me and/or post patches at the RT bug links below. There are many methods that could be added to this module (profile editing, for example). If you find yourself using the "submit_form" method, it probably means you should write whatever you're editing into a method and post it on RT.
See the TODO section above for starters.
BUGS
Please report any bugs or feature requests, or send any patches, 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.
IF YOU USE A MAIL SERVICE (or program) WITH JUNK MAIL FILTERING, especially HOTMAIL or YAHOO, add the bug reporting email address above to your address book so that you can receive status updates.
Bug reports are nice, patches are nicer.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::MyspaceYou can also look for information at:
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
RT: CPAN's request tracker
Search CPAN
COPYRIGHT & LICENSE
Copyright 2005-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.