NAME

WWW::Myspace - Access MySpace.com profile information from Perl

VERSION

Version 0.17

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

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).

Methods

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.

EXAMPLES
    use WWW::Myspace;
    my $myspace = new WWW::Myspace;
    
    # 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";

my_friend_id

Returns the friendID of the user you're logged in as.

EXAMPLE

print $myspace->my_friend_id;

account_name

Returns the account name (email address) under which you're logged in. Note that the account anem is retreived from the user or from your program depending on how you called the "new" method.

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;

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_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.

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;

cookie_jar

Returns the path to the file we're using to store cookies. Defaults to $ENV{'HOME'}/.cookies.txt. If called with a filename, sets cookie_jar to that path.

If using this from a CGI script, you should set cookie_jar.

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, 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.

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.

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;

friends_who_emailed

Returns list of the friend IDs of 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".

@friends = $myspace->friends_who_emailed;

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=".

get_page( $url )

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 5-second delay between attempts. 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;

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 6229, Tom's ID.

EXAMPLE:

List the friendIDs mentioned on Tom's profile:

use WWW::Myspace;
my $myspace = new WWW::Myspace;

$res = $myspace->get_profile( 6229 );

@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";
}

get_profile( $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;

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: Posted. This means the post went through and we read the
			phrase we needed from the resulting page.
PA: Posted, requires approval
FN: Failed Network. The POST returned a bad status.
FC: Failed. A CAPTCHA response was requested.
FF: Failed. Got "You must be someone's friend to post a comment" error.
F: Failed. The post went through, but we didn't get the phrase
			we needed to verify that it was ok.

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.

EXAMPLE: use WWW::Myspace; my $myspace = new WWW::Myspace;

foreach $id ( $myspace->friends_who_emailed ) {
    $status = $myspace->post_comment( $id, "Thanks for the message!" )
}

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).

If called in the second form, it uses the "already_commented" method to determine if a comment has already been left on each friend's page and skips the page if it detects a previous comment.

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!"
	  	)
	  }
  }

send_message( $friend_id, $subject, $message )

Send a message to the user identified by $friend_id.

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).

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.

EXAMPLE

# 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_ids )

Send a friend request to each friend in the list of @friend_ids.

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.

$myspace->send_friend_request( 12345, 123456 );

Returns 1 if all requests were submitted ok, 0 if any failed.

add_as_friend

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 as friend".

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.

(This method is a bit inefficient if deleting more than one friend due to a documented bug in HTTP::Request::Form. It should probably be moved to WWW::Mechanize.)

submit_form( $url, $form_no, $button, $fields_ref )

This powerful little method reads the web page specified by $url, finds the form specified by $form_no, 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 :).

$url can either be a text string to a URL, or a reference to an HTTP::Response object that contains the source of the page that contains the form.

$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 to "1". For the first form, use "0".

$button is the name or type of button to submit. This will frequently be "submit", but if they've named the button something clever like "Submit22" (as MySpace does in their login form), then you may have to use that.

$fields_ref is a reference to a hash that contains field names and values you want to fill in on the form.

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" }
				);

# Confirm it
$self->submit_form( $self->{current_page}, 1, "submit", {} );

The comment form is a 2-step process. The first command gets the form and fills it in, then posts it. WWW::Myspace then returns the HTML display of the form with a "Post Comment" button. So we just need to click that button ("Post Comment" is the button's "value", but its type is "submit". You could probably use either value. See the "press" method in "perldoc HTTP::Request::Form" for more info). We send that confirmation page to submit_form as a reference to the page returned by the first post.

AUTHOR

Grant Grueninger, <grantg at cpan.org>

KNOWN ISSUES

-: 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).

TODO

Add an option to include the "add to friends" button after a message automatically.

Hint:
<a href="http://www.myspace.com/index.cfm?fuseaction=invite.addfriend_verify&friendID=37033247"><img src="http://i.myspace.com/site/images/addFriendIcon.gif" alt="Add as friend"></a>
(Replace "37033247" with your friend ID)

Have 'add_to_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.

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.

Bug reports are nice, patches are nicer.

SUPPORT

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

perldoc WWW::Myspace

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 & LICENSE

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

To install WWW::Myspace, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WWW::Myspace

CPAN shell

perl -MCPAN -e shell
install WWW::Myspace

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

Methods

new( $account, $password )

new( )

my_friend_id

account_name

user_name

friend_count

current_page

cookie_jar

cache_dir

cache_file

remove_cache

make_cache_dir

get_friends

friends_who_emailed

friends_in_group( group_id )

get_page( $url )

get_friends_on_page( $friends_page );

get_profile( $friend_id )

post_comment( $friend_id, $message )

comment_friends( $message )

comment_friends( $message, { 'ignore_dup' => 1 } )

already_commented

send_message( $friend_id, $subject, $message )

approve_friend_requests( [message] )

send_friend_request( @friend_ids )

add_as_friend

delete_friend( @friend_ids )

submit_form( $url, $form_no, $button, $fields_ref )

AUTHOR

KNOWN ISSUES

TODO

CONTRIBUTING

BUGS

SUPPORT

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Module Install Instructions