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 the Net::Jabber Client, Component, and Server
objects. 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 qw( Client );
$Con = new Net::Jabber::Client(); # From
$status = $Con->Connect(name=>"jabber.org"); # Net::Jabber::Client
or
use Net::Jabber qw( Component );
$Con = new Net::Jabber::Component(); #
$status = $Con->Connect(name=>"jabber.org", # From
secret=>"bob"); # Net::Jabber::Component
$Con->SetCallBacks(send=>\&sendCallBack,
receive=>\&receiveCallBack,
message=>\&messageCallBack,
iq=>\&handleTheIQTag);
$Con->SetIQCallBacks("jabber:iq:roster"=>
{
get=>\&iqRosterGetCB,
set=>\&iqRosterSetCB,
result=>\&iqRosterResultCB,
},
etc...
);
$Con->Info(name=>"Jarl",
version=>"v0.6000");
$error = $Con->GetErrorCode();
$Con->SetErrorCode("Timeout limit reached");
$Con->Process();
$Con->Process(5);
$Con->Send($object);
$Con->Send("<tag>XML</tag>");
$Con->Send($object,1);
$Con->Send("<tag>XML</tag>",1);
$Con->Disconnect();ID Functions
$id = $Con->SendWithID($sendObj);
$id = $Con->SendWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID($sendObj);
$receiveObj = $Con->SendAndReceiveWithID($sendObj,
10);
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>",
5);
$yesno = $Con->ReceivedID($id);
$receiveObj = $Con->GetID($id);
$receiveObj = $Con->WaitForID($id);
$receiveObj = $Con->WaitForID($id,
20);Namespace Functions
$Con->DefineNamespace(xmlns=>"foo:bar",
type=>"Query",
functions=>[{name=>"Foo",
get=>"foo",
set=>["scalar","foo"],
defined=>"foo",
hash=>"child-data"},
{name=>"Bar",
get=>"bar",
set=>["scalar","bar"],
defined=>"bar",
hash=>"child-data"},
{name=>"FooBar",
get=>"__netjabber__:master",
set=>["master"]}]);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();
$Con->PresenceSend(type=>"unavailable");
$Con->PresenceSend(show=>"away");
$Con->PresenceSend(signature=>...signature...);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");Presence DB 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");IQ::Browse Functions
%hash = $Con->BrowseRequest(jid=>"jabber.org");
%hash = $Con->BrowseRequest(jid=>"jabber.org",
timeout=>10);IQ::Browse DB Functions
$Con->BrowseDBDelete("jabber.org");
$Con->BrowseDBDelete(Net::Jabber::JID);
$presence = $Con->BrowseDBQuery(jid=>"bob\@jabber.org");
$presence = $Con->BrowseDBQuery(jid=>Net::Jabber::JID);
$presence = $Con->BrowseDBQuery(jid=>"users.jabber.org",
timeout=>10);
$presence = $Con->BrowseDBQuery(jid=>"conference.jabber.org",
refresh=>1);IQ::Last Functions
$Con->LastQuery();
$Con->LastQuery(to=>"bob@jabber.org");
%result = $Con->LastQuery(waitforid=>1);
%result = $Con->LastQuery(to=>"bob@jabber.org",
waitforid=>1);
%result = $Con->LastQuery(to=>"bob@jabber.org",
waitforid=>1,
timeout=>10);
%result = $Con->LastQuery(waitforid=>1,
timeout=>10);
$Con->LastSend(to=>"bob@jabber.org");
$seconds = $Con->LastActivity();IQ::Register Functions
%hash = $Con->RegisterRequest();
%hash = $Con->RegisterRequest(to=>"transport.jabber.org");
%hash = $Con->RegisterRequest(to=>"transport.jabber.org",
timeout=>10);
@result = $Con->RegisterSend(to=>"somewhere",
usersname=>"newuser",
resource=>"New User",
password=>"imanewbie",
email=>"newguy@new.com",
key=>"some key");
@result = $Con->RegisterSendData("users.jabber.org",
first=>"Bob",
last=>"Smith",
nick=>"bob",
email=>"foo@bar.net");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::RPC Functions
$query = $Con->RPCEncode(type=>"methodCall",
methodName=>"methodName",
params=>[param,param,...]);
$query = $Con->RPCEncode(type=>"methodResponse",
params=>[param,param,...]);
$query = $Con->RPCEncode(type=>"methodResponse",
faultCode=>4,
faultString=>"Too many params");
@response = $Con->RPCParse($iq);
@response = $Con->RPCCall(to=>"dataHouse.jabber.org",
methodname=>"numUsers",
params=>[ param,param,... ]
);
$Con->RPCResponse(to=>"you\@jabber.org",
params=>[ param,param,... ]);
$Con->RPCResponse(to=>"you\@jabber.org",
faultCode=>"4",
faultString=>"Too many parameters"
);
$Con->RPCSetCallBacks(myMethodA=>\&methoda,
myMethodB=>\&do_somthing,
etc...
);IQ::Search Functions
%fields = $Con->SearchRequest();
%fields = $Con->SearchRequest(to=>"users.jabber.org");
%fields = $Con->SearchRequest(to=>"users.jabber.org",
timeout=>10);
$Con->SearchSend(to=>"somewhere",
name=>"",
first=>"Bob",
last=>"",
nick=>"bob",
email=>"",
key=>"some key");
$Con->SearchSendData("users.jabber.org",
first=>"Bob",
last=>"",
nick=>"bob",
email=>"");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
$Con->SXPMSend(to=>'bob@jabber.org',
type=>'chat',
boardheight=>400,
boardwidth=>400,
map=>{ '#'=>'',
' '=>'None',
'a'=>'#FFFFFF',
'b'=>'#FF0000',
...
}
data=>"4 .3 . 2 .2 .3 .4 ",
datawidth=>5
);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
SetCallBacks(xdb=>function, <message/>, <presence/>, and
db:verify=>function, <iq/>. If a packet is received
db:result=>function) with an ID which is found in the
SetCallBacks(send=>function, registerd ID list (see RegisterID
receive=>function, below) then it is not sent to
update=>function) these functions, instead it
is inserted into a LIST and can
be retrieved by some functions
we will mention later.
send and receive are used to
log what XML is sent and received.
update is used as way to update
your program while waiting for
a packet with an ID to be
returned (useful for GUI apps).
A major change that came with
the last release is that the
session id is passed to the
callback as the first argument.
This was done to facilitate
the Server module.
The next argument depends on
which callback you are talking
about. message, presence, iq,
xdb, db:verify, and db:result
all get passed in Net::Jabber
objects that match those types.
send and receive get passed in
strings. update gets passed
nothing, not even the session id.
If you set the function to undef,
then the callback is removed from
the list.
SetIQCallBacks(namespace=>{ - sets the callback functions for
get=>function, the specified namespace. The
set=>function, function takes namespaces as the
result=>function main key, and lets you specify a
}, function for each type of packet
etc...) you can get.
"get"
"set"
"result"
When it gets an <iq/> packet it
checks the type='' and the
xmlns='' for a defined callback.
If there is one then if calls
the function with two arguments:
the session ID, and the
Net::Jabber::xxxx object.
If you set the function to undef,
then the callback is removed from
the list.
NOTE: If you use this, which is a cleaner method,
then you must *NOT* specify a callback for
iq in the SetCallBacks function.
Net::Jabber defines a few default
callbacks for various types and
namespaces:
jabber:iq:last(get) -
replies with the current last
activity
jabber:iq:last(result) -
reformats the <iq/> into a
<message/> and submits it as
if the packet was received.
jabber:iq:rpc(set) -
calls the rpc method and
returns the response
jabber:iq:time(get) -
replys with the current time
jabber:iq:time(result) -
reformats the <iq/> into a
<message/> and submits it as
if the packet was received.
jabber:iq:version(get) -
replys with the info for the
Client/Component (as defined
in the Info function)
jabber:iq:version(result) -
reformats the <iq/> into a
<message/> and submits it as
if the packet was received.
Info(name=>string, - Set some information so that Net::Jabber
version=>string) can auto-reply to some packets for you to
reduce the work you have to do.
NOTE: This requires that you use the
SetIQCallBacks methodolody and not the
SetCallBacks for <iq/> packets.
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
ignoreActivity) an XML string as an argument and sends it to
Send(string, the server. If you set ignoreActivty to 1,
ignoreActivity) then the XML::Stream module will not record
this packet as couting towards user activity.
=head2 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
timeout) provide a complete way to send and
SendAndReceiveWithID(string, receive packets with IDs. Can take
timeout) either a Net::Jabber::xxxxx object
or an XML string. Returns the
proper Net::Jabber::xxxxx object
based on the type of packet
received. The timeout is passed
on to WaitForID, see that function
for how the timeout works.
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.
timeout) Returns the proper Net::Jabber::xxxxx object
based on the type of packet received. If the
timeout limit is reached then if the packet
does come in, it will be discarded.
NOTE: Only <iq/> officially support ids, so sending a <message/>, or
<presence/> with an id is a risk. The server will ignore the
id tag and pass it through, so both clients must support the
id tag for these functions to be useful.Namespace Functions
DefineNamespace(xmlns=>string, - This function is very complex.
type=>string, It is a little too complex to
functions=>array) discuss within the confines of
this small paragraph. Please
refer to the man page for
Net::Jabber::Namespaces for the
full documentation on this
subject.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() - no arguments will send an empty
PresenceSend(hash, Presence to the server to tell it
signature=>string) that you are available. If you
provide a hash, then it will pass
that hash to the SetPresence()
function as defined in the
Net::Jabber::Presence module.
Optionally, you can specify a
signature and a jabber:x:signed
will be placed in the <presence/>.Subscription 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 unsubscribePresence DB 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 jabber:iq:agent
namespace.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::Browse Functions
BrowseRequest(jid=>string, - sends a jabber:iq:browse request to
timeout=>int) the jid passed as an argument, and
returns a hash with the resulting
tree. The format of the hash is:
$browse{'category'} = "conference"
$browse{'children'}->[0]
$browse{'children'}->[1]
$browse{'children'}->[11]
$browse{'jid'} = "conference.jabber.org"
$browse{'name'} = "Jabber.org Conferencing Center"
$browse{'ns'}->[0]
$browse{'ns'}->[1]
$browse{'type'} = "public"
The ns array is an array of the
namespaces that this jid supports.
The children array points to hashs
of this form, and represent the fact
that they can be browsed to.
The timeout arguement is to tell the
system how long to wait before giving
up getting a reply back.IQ::Browse DB Functions
BrowseDBDelete(string|Net::Jabber::JID) - delete thes JID browse
data from the DB.
BrowseDBQuery(jid=>string | NJ::JID, - returns the browse data
timeout=>integer, for the requested JID. If
refresh=>0|1) the DB does not contain
the data for the JID, then
it attempts to fetch the
data via BrowseRequest().
The timeout is passed to
the BrowseRequest() call,
and refresh tells the DB
to request the data, even
if it already has some.IQ::Last Functions
LastQuery(to=>string, - asks the jid specified for its last
waitforid=>0|1, activity. If the to is blank, then it
timeout=>int) queries the server. Returns a hash with
LastQuery() the various items set if waitforid is set
to 1:
$last{seconds} - Seconds since activity
$last{message} - Message for activity
If you specify waitforid, then you can
optionally specify a timeout in seconds.
LastSend(to=>string, - sends the specified last to the specified jid.
hash) the hash is the seconds and message as shown
in the Net::Jabber::Query man page.
LastActivity() - returns the number of seconds since the last activity
by the user.IQ::Register Functions
RegisterRequest(to=>string, - send an <iq/> request to the specified
timeout=>int) server/transport, if not specified it
RegisterRequest() sends to the current active server.
The function returns a hash that
contains the required fields. Here
is an example of the hash:
$hash{fields} - The raw fields from
the iq:register.
To be used if there
is no x:data in the
packet.
$hash{instructions} - How to fill out
the form.
$hash{form} - The new dynamic forms.
In $hash{form}, 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 jabber:iq:register namespace.
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.
RegisterSendData(string|JID, - takes the contents of the hash and
hash) builds a jabebr:x:data return packet
which it sends in a Net::Jabber::Query
jabber:iq:register namespace packet.
The first argument is the JID to send
the packet to.
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 jabber:iq:roster
namespace.
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 jabber:iq:roster
namespace.IQ::RPC Functions
RPCParse(IQ object) - returns an array. The first argument tells
the status "ok" or "fault". The second
argument is an array if "ok", or a hash if
"fault".
RPCCall(to=>jid|string, - takes the methodName and params,
methodName=>string, builds the RPC calls and sends it
params=>array) to the specified address. Returns
the above data from RPCParse.
RPCResponse(to=>jid|string, - generates a response back to
params=>array, the caller. If any part of
faultCode=>int, fault is specified, then it
faultString=>string) wins.
Note: To ensure that you get the correct type for a param sent
back, you can specify the type by prepending the type to
the value:
"i4:5"
"boolean:0"
"string:56"
"double:5.0"
"dateTime:20020415T11:11:11"
"base64:...."
RPCSetCallBacks(method=>function, - sets the callback functions
method=>function, for the specified methods.
etc...) The method comes from the
<methodName/> and is case
sensitive. The single
arguemnt is a ref to an
array that contains the
<params/>. The function you
write should return one of two
things:
["ok", [...] ]
The [...] is a list of the
<params/> you want to return.
["fault", {faultCode=>1,
faultString=>...} ]
If you set the function to undef,
then the method is removed from
the list.IQ::Search Functions
SearchRequest(to=>string, - send an <iq/> request to the specified
timeout=>int) server/transport, if not specified it
SearchRequest() sends to the current active server.
The function returns a hash that
contains the required fields. Here
is an example of the hash:
$hash{fields} - The raw fields from
the iq:register. To
be used if there is
no x:data in the
packet.
$hash{instructions} - How to fill out
the form.
$hash{form} - The new dynamic forms.
In $hash{form}, the fields that are
present are the required fields the
server needs.
SearchSend(to=>string|JID, - takes the contents of the hash and
hash) passes it to the SetSearch function
in the Net::Jabber::Query
jabber:iq:search namespace. And then
sends the packet.
SearchSendData(string|JID, - takes the contents of the hash and
hash) builds a jabebr:x:data return packet
which it sends in a Net::Jabber::Query
jabber:iq:search namespace packet.
The first argument is the JID to send
the packet to.IQ::Time Functions
TimeQuery(to=>string, - asks the jid specified for its localtime.
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
SXPMSend(to=>string, - sends the specified sxpm information to the
type=>string, jid in the to with the message type being
hash) set in the type. See the Net::Jabber::SXPM
module for valid values for the hash.
This function returns the
Net::Jabber::Message object sent to the jid.AUTHOR
By Ryan Eatmon in February of 2002 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.