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
$status = $Con->Connect(name=>"jabber.org"); #
or
$Con = new Net::Jabber::Transport(); #
$status = $Con->Connect(name=>"jabber.org", # From Net::Jabber::Transport
secret=>"bob"); #
$Con->SetCallBacks(send=>\&sendCallBack,
receive=>\&receiveCallBack,
message=>\&messageCallBack,
iq=>\&handleTheIQTag);
$error = $Con->GetErrorCode();
$Con->SetErrorCode("Timeout limit reached");
$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);Namespace Functions
$Con->AddDelegate(parentttype=>"query",
namespace=>"foo::bar",
parent=>"Foo::Bar");
$Con->AddDelegate(parenttype=>"x",
namespace=>"foo::bar::bob",
parent=>"Foo::Bar",
delegate=>"Foo::Bar::Bob");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",
to=>"bob@jabber.org");
$Con->Subscription(type=>"unsubscribe",
to=>"bob@jabber.org");
$Con->Subscription(type=>"subscribed",
to=>"bob@jabber.org");
$Con->Subscription(type=>"unsubscribed",
to=>"bob@jabber.org");PresenceDB Functions
$Con->PresenceDBParse(Net::Jabber::Presence);
$Con->PresenceDBDelete("bob\@jabber.org");
$Con->PresenceDBDelete(Net::Jabber::JID);
$presence = $Con->PresenceDBQuery("bob\@jabber.org");
$presence = $Con->PresenceDBQuery(Net::Jabber::JID);
@resources = $Con->PresenceDBResources("bob\@jabber.org");
@resources = $Con->PresenceDBResources(Net::Jabber::JID);IQ Functions
IQ::Agents Functions
%agents = $Con->AgentsGet();
%agents = $Con->AgentsGet(to=>"transport.jabber.org");IQ::Auth Functions
@result = $Con->AuthSend();
@result = $Con->AuthSend(username=>"bob",
password=>"bobrulez",
resource=>"Bob");
@result = $Con->RestZeroK(password=>"foobar");IQ::Register Functions
%fields = $Con->RegisterRequest();
%fields = $Con->RegisterRequest(to=>"transport.jabber.org");
@result = $Con->RegisterSend(usersname=>"newuser",
resource=>"New User",
password=>"imanewbie",
email=>"newguy@new.com",
key=>"some key");IQ::Roster Functions
%roster = $Con->RosterParse($iq);
%roster = $Con->RosterGet();
$Con->RosterAdd(jid=>"bob\@jabber.org",
name=>"Bob");
$Con->RosterRemove(jid=>"bob@jabber.org");IQ::Search Functions
%fields = $Con->SearchRequest();
%fields = $Con->SearchRequest(to=>"users.jabber.org");
$Con->SearchSend(name=>"",
first=>"Bob",
last=>"",
nick=>"bob",
email=>"",
key=>"som key");IQ::Time Functions
$Con->TimeQuery();
$Con->TimeQuery(to=>"bob@jabber.org");
%result = $Con->TimeQuery(waitforid=>1);
%result = $Con->TimeQuery(to=>"bob@jabber.org",
waitforid=>1);
$Con->TimeSend(to=>"bob@jabber.org");IQ::Version Functions
$Con->VersionQuery();
$Con->VersionQuery(to=>"bob@jabber.org");
%result = $Con->VersionQuery(waitforid=>1);
%result = $Con->VersionQuery(to=>"bob@jabber.org",
waitforid=>1);
$Con->VersionSend(to=>"bob@jabber.org",
name=>"Net::Jabber",
ver=>"1.0a",
os=>"Perl");X Functions
METHODS
Basic Functions
GetErrorCode() - returns a string that will hopefully contain some
useful information about why a function returned
an undef to you.
SetErrorCode(string) - set a useful error message before you return
an undef to the caller.
SetCallBacks(message=>function, - sets the callback functions for
presence=>function, the top level tags listed. The
iq=>function, available tags to look for are
send=>function, <message/>, <presence/>, and
receive=>function) <iq/>. If a packet is received
with an ID which is found in the
registerd ID list (see RegisterID
below) 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.Namespace Functions
AddDelegate(parenttype=>string, - this tells the Net::Jabber modules
namespace=>string, about the new namespace. The
parent=>string, namespaces determines how the xmlns
delegate=>string) looks in the tag. The parent is
the name of the module to create
when you use this namespace. The
delegate is only needed if the
parent module uses delegates to
distinguish between namespaces
(like the Net::Jabber::IQ and
Net::Jabber::X modules do). The
delegate must be a valid Perl
Module. The parenttype specifies
the type of namespace this is in
the Jabber world. (Added to allow
namespaces to be reused between
Query, X, and Data.) The current
valid settings for parenttype are:
query for <iq/> queries
x for <x/> packets
data for <xdb/> data
The way to determine which one
to use is figure out which one
of the above best fits the mode
that you are using this namespace
in.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(hash) - taks the hash and passes it to SetPresence in
Net::Jabber::Presence (refer there for valid
settings). Then it sends the subscription to
server.
The valid types of subscription are:
subscribe - subscribe to JID's presence
unsubscribe - unsubscribe from JID's presence
subscribed - response to a subscribe
unsubscribed - response to an unsubscribePresenceDB Functions
PresenceDBParse(Net::Jabber::Presence) - for every presence that you
receive pass the Presence
object to the DB so that
it can track the resources
and priorities for you.
Returns either the presence
passed in, if it not able
to parsed for the DB, or the
current presence as found by
the PresenceDBQuery function.
PresenceDBDelete(string|Net::Jabber::JID) - delete thes JID entry
from the DB.
PresenceDBQuery(string|Net::Jabber::JID) - returns the NJ::Presence
that was last received for
the highest priority of this
JID. You can pass it a
string or a NJ::JID object.
PresenceDBResources(string|Net::Jabber::JID) - returns an array of
resources in order
from highest priority
to lowest.IQ Functions
IQ::Agents Functions
AgentsGet(to=>string, - takes all of the information and
AgentsGet() builds a Net::Jabber::IQ::Agents packet.
It then sends that packet either to the
server, or to the specified transport,
with an ID and waits for that ID to return.
Then it looks in the resulting packet and
builds a hash that contains the values
of the agent list. The hash is layed out
like this: (NOTE: the jid is the key to
distinguish the various agents)
$hash{<JID>}->{order} = 4
->{name} = "ICQ Transport"
->{transport} = "ICQ #"
->{description} = "ICQ...blah..."
->{service} = "icq"
->{register} = 1
->{search} = 1
etc...
The order field determines the order that
it came from the server in... in case you
care. For more info on the valid fields
see the Net::Jabber::Query::Agent module.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
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.
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::Register Functions
RegisterRequest(to=>string) - send an <iq/> request to the specified
RegisterRequest() server/transport, if not specified it
sends to the current active server.
The function returns a hash that
contains the required fields. Here
is an example of the hash:
$fields{intructions} = "do this..."
$fields{key} = "some key"
$fields{username} = ""
...
The fields that are present are the
required fields the server needs.
RegisterSend(hash) - takes the contents of the hash and passes it
to the SetRegister function in the module
Net::Jabber::Query::Register. This function
returns an array that looks like this:
[ type , message ]
If type is "ok" then registration was
successful, otherwise message contains a
little more detail about the error.IQ::Roster Functions
RosterParse(IQ object) - returns a hash that contains the roster
parsed into the following data structure:
$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
RosterGet() - sends an empty Net::Jabber::IQ::Roster tag to the
server so the server will send the Roster to the
client. Returns the above hash from RosterParse.
RosterAdd(hash) - sends a packet asking that the jid be
added to the roster. The hash format
is defined in the SetItem function
in the Net::Jabber::Query::Roster::Item
module.
RosterRemove(hash) - sends a packet asking that the jid be
removed from the roster. The hash
format is defined in the SetItem function
in the Net::Jabber::Query::Roster::Item
module.IQ::Search Functions
SearchRequest(to=>string) - send an <iq/> request to the specified
SearchRequest() server/transport, if not specified it
sends to the current active server.
The function returns a hash that
contains the required fields. Here
is an example of the hash:
$fields{intructions} = "do this..."
$fields{key} = "some key"
$fields{name} = ""
...
The fields that are present are the
required fields the server needs. If
the hash is undefined then there was
an error with the request.
SearchSend(to=>string|JID, - takes the contents of the hash and
hash) passes it to the SetSearch function
in the module Net::Jabber::Query::Search.
And then send the packet.IQ::Time Functions
TimeQuery(to=>string, - asks the jid specified for its local time.
waitforid=>0|1) If the to is blank, then it queries the
TimeQuery() server. Returns a hash with the various
items set if waitforid is set to 1:
$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
waitforid=>0|1) client version information. If the
VersionQuery() to is blank, then it queries the
server. Returns ahash with the
various items set if waitforid is
set to 1:
$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
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.