NAME

Net::YMSG - An updated interface to Yahoo Messenger protocol 11.

SYNOPSIS

  use Net::YMSG;

  my $yahoo = new Net::YMSG;

  ...

METHODS

Net::YMSG new (hash options)

Create a new object.

void setHandlers, setHandler (Event => CODE, ...)

Define an event handler. setHandlers is a grammatical alias for setHandler.

CONNECTION METHODS

bool connect ([string YahooID, string password])

Attempt to connect to Yahoo's network. If you didn't previously define a YahooID and Password (e.g. in the constructor) you can pass them into this method.

bool do_one_loop ()

Run a single event loop with the server. This will receive any events that the server is sending to our client and act on them accordingly. As long as the connection stays up, this method returns true.

void logoff ()

Sign out of Yahoo.

void setStatus (int status[, string custommessage])

Change your online status. status is one of the following:

  YMSG_STATUS_ONLINE
  YMSG_STATUS_AWAY

Additionally you may set a custom away message when going away.

void sendMessage (string YahooID, string message)

Send an instant message to YahooID.

void sendTyping (string YahooID, bool status)

Send a typing notification to YahooID. status can be one of:

  YMSG_TYPING_STARTED  1
  YMSG_TYPING_STOPPED  0

void sendBuzz (string YahooID)

Send a "buzz!" to YahooID.

void addBuddy (string YahooID, string Group)

Add a buddy to your buddy list. Both YahooID and Group are required.

void removeBuddy (string YahooID, string Group)

Remove a buddy from your buddy list. Both YahooID and Group are required.

void acceptBuddy (string YahooID)

If you got a NewContact event from YahooID requesting to add you to their buddy list, respond by calling this method to accept it. Otherwise, call rejectBuddy.

void rejectBuddy (string YahooID, string message)

Reject a buddy's add request and send message as your reason why.

UTILITY METHODS

string statusToString (int status)

Turn a status number into a human-readable string. Potential strings are:

  ONLINE
  BRB
  BUSY
  NOTATHOME
  NOTATDESK
  NOTINOFFICE
  ONPHONE
  ONVACATION
  OUTTOLUNCH
  STEPPEDOUT
  INVISIBLE
  CUSTOM
  IDLE
  OFFLINE
  TYPING

Returns undef if not known.

INTERNAL METHODS

You should refrain from calling these methods manually.

void send (int service => body)

Prepare a YMSG packet and send it.

hash parseParams (bin data)

Turn the binary param data into a hashref and return it.

string format_id (string YahooID)

Format a Yahoo! ID (lowercase it).

HANDLERS

Connected (YMSG)

This event is called after the authentication with the server was successful.

List (YMSG, array Buddies, array Groups)

The server has sent your buddy list information. Buddies and Groups are arrayrefs containing your buddy list.

Message (YMSG, string YahooID, string message)

The user YahooID has sent you a message over IM.

Typing (YMSG, string YahooID, bool typing)

The user YahooID has started or stopped typing. typing will be 1 if the user is typing and 0 if they've stopped.

Status (YMSG, string YahooID, int status[, string message])

A user on your buddy list has changed their status. status will be a status code similar to what you would use in setStatus(). If they have a custom status message, message will be that message.

You can get a human-readable version of their status by calling statusToString().