NAME
Net::Jabber::Protocol - Jabber Protocol Library
SYNOPSIS
Net::Jabber::Protocol is a module that provides a developer easy access
to the Jabber Instant Messaging protocol. It provides high level functions
to both Net::Jabber::Client and Net::Jabber::Transport. These functions
are automatically indluded in those modules through AUTOLOAD and delegates.DESCRIPTION
Protocol.pm seeks to provide enough high level APIs and automation of
the low level APIs that writing a Jabber Client/Transport in Perl is
trivial. For those that wish to work with the low level you can do
that too, but those functions are covered in the documentation for
each module.
Net::Jabber::Protocol provides functions to login, send and receive
messages, set personal information, create a new user account, manage
the roster, and disconnect. You can use all or none of the functions,
there is no requirement.
For more information on how the details for how Net::Jabber is written
please see the help for Net::Jabber itself.
For more information on writing a Client see Net::Jabber::Client.
For more information on writing a Transport see Net::Jabber::Transport.Basic Functions
use Net::Jabber;
$Con = new Net::Jabber::Client(); # From Net::Jabber::Client
$Con->Connect(name=>"jabber.org"); #
or
$Con = new Net::Jabber::Transport(); #
$Con->Connect(name=>"jabber.org", # From Net::Jabber::Transport
secret=>"bob"); #
$Con->SetCallBacks(message=>\&messageCallBack,
iq=>\&handleTheIQTag);
$Con->Process();
$Con->Process(5);
$Con->Send($object);
$Con->Send("<tag>XML</tag>");
$Con->Disconnect();ID Functions
$id = $Con->SendWithID($sendObj);
$id = $Con->SendWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID($sendObj);
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
$yesno = $Con->ReceivedID($id);
$receiveObj = $Con->GetID($id);
$receiveObj = $Con->WaitForID($id);Message Functions
$Con->MessageSend(to=>"bob@jabber.org",
subject=>"Lunch",
body=>"Let's go grab some...\n";
thread=>"ABC123",
priority=>10);Presence Functions
$Con->PresenceSend();Subscription Functions
$Con->Subscription(type=>"subscribe",
jid=>"bob@jabber.org");
$Con->Subscription(type=>"unsubscribe",
jid=>"bob@jabber.org");
$Con->Subscription(type=>"subscribed",
jid=>"bob@jabber.org");
$Con->Subscription(type=>"unsubscribed",
jid=>"bob@jabber.org");IQ Functions
$Con->SetQueryDelegates("com:bar:foo"=>"Foo::Bar");IQ::Auth Functions
@result = $Con->AuthSend();
@result = $Con->AuthSend(username=>"bob",
password=>"bobrulez",
resource=>"Bob");IQ::Fneg Functions
n/aIQ::Info Functions
n/aIQ::Register Functions
@result = $Con->RegisterSend(usersname=>"newuser",
resource=>"New User",
password=>"imanewbie");IQ::Resource Functions
n/aIQ::Roster Functions
%roster = $Con->RosterGet();
$Con->RosterAdd(jid=>"bob@jabber.org");
$Con->RosterRemove(jid=>"bob@jabber.org");IQ::Time Functions
%result = $Con->TimeQuery();
%result = $Con->TimeQuery(to=>"bob@jabber.org");
$Con->TimeSend(to=>"bob@jabber.org");IQ::Version Functions
%result = $Con->VersionQuery();
%result = $Con->VersionQuery(to=>"bob@jabber.org");
$Con->VersionSend(to=>"bob@jabber.org",
name=>"Net::Jabber",
ver=>"1.0a",
os=>"Perl");X Functions
$Con->SetXDelegates("com:bar:foo"=>"Foo::Bar");METHODS
Basic Functions
SetCallBacks(message=>function, - sets the callback functions for
presence=>function, the top level tags listed. The
iq=>function) available tags to look for are
<message/>, <presence/>, and
<iq/>. If a packet is received
with an ID then it is not sent
to these functions, instead it
is inserted into a LIST and can
be retrieved by some functions
we will mention later.
Process(integer) - takes the timeout period as an argument. If no
timeout is listed then the function blocks until
a packet is received. Otherwise it waits that
number of seconds and then exits so your program
can continue doing useful things. NOTE: This is
important for GUIs. You need to leave time to
process GUI commands even if you are waiting for
packets.
IMPORTANT: You need to check the output of every
Process. If you get an undef or "" then the
connection died and you should behave accordingly.
Send(object) - takes either a Net::Jabber::xxxxx object or an XML
Send(string) string as an argument and sends it to the server.ID Functions
SendWithID(object) - takes either a Net::Jabber::xxxxx object or an
SendWithID(string) XML string as an argument, adds the next
available ID number and sends that packet to
the server. Returns the ID number assigned.
SendAndReceiveWithID(object) - uses SendWithID and WaitForID to
SendAndReceiveWithID(string) provide a complete way to send and
receive packets with IDs. Can take
either a Net::Jabber::xxxxx object
or an XML string. Returns the
proper Net::Jabber::xxxxx object
based on the type of packet received.
ReceivedID(integer) - returns 1 if a packet has been received with
specified ID, 0 otherwise.
GetID(integer) - returns the proper Net::Jabber::xxxxx object based
on the type of packet received with the specified
ID. If the ID has been received the GetID returns
0.
WaitForID(integer) - blocks until a packet with the ID is received.
Returns the proper Net::Jabber::xxxxx object
based on the type of packet received
NOTE: Only <iq/> officially support ids, so sending a <message/>, or
<presence/> with an id is a risk. Both clients must support
this for these functions to work.Message Functions
MessageSend(hash) - takes the hash and passes it to SetMessage in
Net::Jabber::Message (refer there for valid
settings). Then it sends the message to the
server.Presence Functions
PresenceSend() - sends an empty Presence to the server to tell it
that you are availableSubscription Functions
Subscription(type=>string, - sends a Presence to the server to tell it
jid=>string) to perform the subscription in type to the
you to the specified JID. The allowed
types are:
subscribe - subscribe to JID's presence
unsubscribe - unsubscribe from JID's presence
subscribed - response to a subscribe
unsubscribed - response to an unsubscribe
IQ Functions
SetQueryDelegates(hash) - the hash gets sent to the
Net::Jabber::Query::SetDelegates function.
For more information about this function,
read the manpage for Net::Jabber::Query.IQ::Auth Functions
AuthSend(username=>string, - takes all of the information and
password=>string, builds a Net::Jabber::IQ::Auth packet.
resource=>string) It then sends that packet to the
AuthSend() server with an ID and waits for that
ID to return. Then it looks in
resulting packet and determines if
authentication was successful for not.
If no hash is passed then it tries
to open an anonymous session. The
array returned from AuthSend looks
like this:
[ type , message ]
If type is "ok" then authentication
was successful, otherwise message
contains a little more detail about the
error.IQ::Fneg Functions
n/aIQ::Info Functions
n/aIQ::Register Functions
RegisterSend(username=>string, - takes all of the information and
password=>string, builds a Net::Jabber::IQ::Register
resource=>string) packet. It then sends that packet
to the server with an ID and waits
for that ID to return. Then it
looks in resulting packet and
determines if registration was
successful for not. The array
returned from RegisterSend looks
like this:
[ type , message ]
If type is "ok" then registration
was successful, otherwise message
contains a little more detail about the
error.IQ::Resource Functions
n/aIQ::Roster Functions
RosterGet() - sends an empty Net::Jabber::IQ::Roster tag to the
server so the server will send the Roster to the
client. Then it takes the result and puts it into
the following data structure which it returns to
to the caller:
$roster{'bob@jabber.org'}->{name}
- Name you stored in the roster
$roster{'bob@jabber.org'}->{subscription}
- Subscription status
(to, from, both, none)
$roster{'bob@jabber.org'}->{ask}
- The ask status from this user
(subscribe, unsubscribe)
$roster{'bob@jabber.org'}->{groups}
- Array of groups that
bob@jabber.org is in
RosterAdd(jid=>string) - sends a packet asking that the jid be
added to the user's roster.
RosterRemove(jid=>string) - sends a packet asking that the jid be
removed from the user's roster.IQ::Time Functions
TimeQuery(to=>string) - asks the jid specified for its local time.
TimeQuery() If the to is blank, then it queries the
server. Returns a hash with the various
items set:
$time{utc} - Time in UTC
$time{tz} - Timezone
$time{display} - Display string
TimeSend(to=>string) - sends the current UTC time to the specified
jid.IQ::Version Functions
VersionQuery(to=>string) - asks the jid specified for its client
VersionQuery() version information. If the to is blank,
then it queries the server. Returns a
hash with the various items set:
$version{name} - Name
$version{ver} - Version
$version{os} - Operating System/Platform
VersionSend(to=>string, - sends the specified version information
name=>string, to the jid specified in the to.
ver=>string,
os=>string)X Functions
SetXDelegates(hash) - the hash gets sent to the
Net::Jabber::X::SetDelegates function. For
more information about this function, read
the manpage for Net::Jabber::X.AUTHOR
Revised by Ryan Eatmon in December 1999.
By Thomas Charron in July of 1999 for http://jabber.org..
Based on a screenplay by Jeremie Miller in May of 1999 for http://jabber.org/
COPYRIGHT
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.