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.
Modes
Several of the functions take a mode argument that let you specify how
the function should behave:
block - send the packet with an ID, and then block until an answer
comes back. You can optionally specify a timeout so that
you do not block forever.
nonblock - send the packet with an ID, but then return that id and
control to the master program. Net::Jabber is still
tracking this packet, so you must use the CheckID function
to tell when it comes in. (This might not be very
useful...)
passthru - send the packet with an ID, but do NOT register it with
Net::Jabber, then return the ID. This is useful when
combined with the XPath function because you can register
a one shot function tied to the id you get back.
Basic Functions
use Net::Jabber qw( Client );
$Con = new Net::Jabber::Client(); # From
$status = $Con->Connect(hostname=>"jabber.org"); # Net::Jabber::Client
or
use Net::Jabber qw( Component );
$Con = new Net::Jabber::Component(); #
$status = $Con->Connect(hostname=>"jabber.org", # From
secret=>"bob"); # Net::Jabber::Component
#
# For callback setup, see Net::XMPP::Protocol
#
$Con->Info(name=>"Jarl",
version=>"v0.6000");
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);
IQ Functions
Agents Functions
%agents = $Con->AgentsGet();
%agents = $Con->AgentsGet(to=>"transport.jabber.org");
Browse Functions
%hash = $Con->BrowseRequest(jid=>"jabber.org");
%hash = $Con->BrowseRequest(jid=>"jabber.org",
timeout=>10);
$id = $Con->BrowseRequest(jid=>"jabber.org",
mode=>"nonblock");
$id = $Con->BrowseRequest(jid=>"jabber.org",
mode=>"passthru");
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);
Bystreams Functions
%hash = $Con->ByteStreamsProxyRequest(jid=>"proxy.server");
%hash = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
timeout=>10);
$id = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
mode=>"nonblock");
$id = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
mode=>"passthru");
%hash = $Con->ByteStreamsProxyParse($query);
$status = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
jid=>"proxy.server");
$status = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
jid=>"proxy.server",
timeout=>10);
$id = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
jid=>"proxy.server",
mode=>"nonblock");
$id = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
jid=>"proxy.server",
mode=>"passthru");
$jid = $Con->ByteStreamsOffer(sid=>"stream_id",
streamhosts=>[{jid=>"jid",
host=>"host",
port=>"port",
zeroconf=>"zero",
},
...
],
jid=>"bob\@jabber.org");
$jid = $Con->ByteStreamsOffer(sid=>"stream_id",
streamhosts=>[{},{},...],
jid=>"bob\@jabber.org",
timeout=>10);
$id = $Con->ByteStreamsOffer(sid=>"stream_id",
streamhosts=>[{},{},...],
jid=>"bob\@jabber.org",
mode=>"nonblock");
$id = $Con->ByteStreamsOffer(sid=>"stream_id",
streamhosts=>[{},{},...],
jid=>"bob\@jabber.org",
mode=>"passthru");
Disco Functions
%hash = $Con->DiscoInfoRequest(jid=>"jabber.org");
%hash = $Con->DiscoInfoRequest(jid=>"jabber.org",
node=>"node...");
%hash = $Con->DiscoInfoRequest(jid=>"jabber.org",
node=>"node...",
timeout=>10);
$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
mode=>"nonblock");
$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
node=>"node...",
mode=>"nonblock");
$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
mode=>"passthru");
$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
node=>"node...",
mode=>"passthru");
%hash = $Con->DiscoInfoParse($query);
%hash = $Con->DiscoItemsRequest(jid=>"jabber.org");
%hash = $Con->DiscoItemsRequest(jid=>"jabber.org",
timeout=>10);
$id = $Con->DiscoItemsRequest(jid=>"jabber.org",
mode=>"nonblock");
$id = $Con->DiscoItemsRequest(jid=>"jabber.org",
mode=>"passthru");
%hash = $Con->DiscoItemsParse($query);
Feature Negotiation Functions
%hash = $Con->FeatureNegRequest(jid=>"jabber.org",
features=>{ feat1=>["opt1","opt2",...],
feat2=>["optA","optB",...]
}
);
%hash = $Con->FeatureNegRequest(jid=>"jabber.org",
features=>{ ... },
timeout=>10);
$id = $Con->FeatureNegRequest(jid=>"jabber.org",
features=>{ ... },
mode=>"nonblock");
$id = $Con->FeatureNegRequest(jid=>"jabber.org",
features=>{ ... },
mode=>"passthru");
my $query = $self->FeatureNegQuery(\{ ... });
$iq->AddQuery($query);
%hash = $Con->FeatureNegParse($query);
File Transfer Functions
$method = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
sid=>"stream_id",
filename=>"/path/to/file",
methods=>["http://jabber.org/protocol/si/profile/bytestreams",
"jabber:iq:oob",
...
]
);
$method = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
sid=>"stream_id",
filename=>"/path/to/file",
methods=>\@methods,
timeout=>"10");
$id = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
sid=>"stream_id",
filename=>"/path/to/file",
methods=>\@methods,
mode=>"nonblock");
$id = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
sid=>"stream_id",
filename=>"/path/to/file",
methods=>\@methods,
mode=>"passthru");
Last Functions
$Con->LastQuery();
$Con->LastQuery(to=>"[email protected]");
%result = $Con->LastQuery(mode=>"block");
%result = $Con->LastQuery(to=>"[email protected]",
mode=>"block");
%result = $Con->LastQuery(to=>"[email protected]",
mode=>"block",
timeout=>10);
%result = $Con->LastQuery(mode=>"block",
timeout=>10);
$Con->LastSend(to=>"[email protected]");
$seconds = $Con->LastActivity();
Multi-User Chat Functions
$Con->MUCJoin(room=>"jabber",
server=>"conference.jabber.org",
nick=>"nick");
$Con->MUCJoin(room=>"jabber",
server=>"conference.jabber.org",
nick=>"nick",
password=>"secret");
Register Functions
@result = $Con->RegisterSendData("users.jabber.org",
first=>"Bob",
last=>"Smith",
nick=>"bob",
email=>"[email protected]");
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...
);
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=>"");
Time Functions
$Con->TimeQuery();
$Con->TimeQuery(to=>"[email protected]");
%result = $Con->TimeQuery(mode=>"block");
%result = $Con->TimeQuery(to=>"[email protected]",
mode=>"block");
$Con->TimeSend(to=>"[email protected]");
Version Functions
$Con->VersionQuery();
$Con->VersionQuery(to=>"[email protected]");
%result = $Con->VersionQuery(mode=>"block");
%result = $Con->VersionQuery(to=>"[email protected]",
mode=>"block");
$Con->VersionSend(to=>"[email protected]",
name=>"Net::Jabber",
ver=>"1.0a",
os=>"Perl");
METHODS
Basic Functions
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 methodology and not the
SetCallBacks for <iq/> packets.
IQ Functions
Agents Functions
********************************
* *
* Deprecated in favor of Disco *
* *
********************************
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.
Browse Functions
********************************
* *
* Deprecated in favor of Disco *
* *
********************************
BrowseRequest(jid=>string, - sends a jabber:iq:browse request to
mode=>string, the jid passed as an argument.
timeout=>int) Returns a hash with the resulting
tree if mode is set to "block":
$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.
See MODES above for using the mode
and timeout.
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.
Bytestreams Functions
ByteStreamsProxyRequest(jid=>string, - sends a bytestreams request
mode=>string, to the jid passed as an
timeout=>int) argument. Returns an array
ref with the resulting tree
if mode is set to "block".
See ByteStreamsProxyParse
for the format of the
resulting tree.
See MODES above for using
the mode and timeout.
ByteStreamsProxyParse(Net::Jabber::Query) - parses the query and
returns an array ref
to the resulting tree:
$host[0]->{jid} = "bytestreams1.proxy.server";
$host[0]->{host} = "proxy1.server";
$host[0]->{port} = "5006";
$host[1]->{jid} = "bytestreams2.proxy.server";
$host[1]->{host} = "proxy2.server";
$host[1]->{port} = "5007";
...
ByteStreamsProxyActivate(jid=>string, - sends a bytestreams activate
sid=>string, to the jid passed as an
mode=>string, argument. Returns 1 if the
timeout=>int) proxy activated (undef if
it did not) if mode is set
to "block".
sid is the stream id that
is being used to talk about
this stream.
See MODES above for using
the mode and timeout.
ByteStreamsOffer(jid=>string, - sends a bytestreams offer
sid=>string, to the jid passed as an
streamhosts=>arrayref argument. Returns the jid
mode=>string, of the streamhost that the
timeout=>int) user selected if mode is set
to "block".
streamhosts is the same
format as the array ref
returned from
ByteStreamsProxyParse.
See MODES above for using
the mode and timeout.
Disco Functions
DiscoInfoRequest(jid=>string, - sends a disco#info request to
node=>string, the jid passed as an argument,
mode=>string, and the node if specified.
timeout=>int) Returns a hash with the resulting
tree if mode is set to "block".
See DiscoInfoParse for the format
of the resulting tree.
See MODES above for using the mode
and timeout.
DiscoInfoParse(Net::Jabber::Query) - parses the query and
returns a hash ref
to the resulting tree:
$info{identity}->[0]->{category} = "groupchat";
$info{identity}->[0]->{name} = "Public Chatrooms";
$info{identity}->[0]->{type} = "public";
$info{identity}->[1]->{category} = "groupchat";
$info{identity}->[1]->{name} = "Private Chatrooms";
$info{identity}->[1]->{type} = "private";
$info{feature}->{http://jabber.org/protocol/disco#info} = 1;
$info{feature}->{http://jabber.org/protocol/muc#admin} = 1;
DiscoItemsRequest(jid=>string, - sends a disco#items request to
mode=>string, the jid passed as an argument.
timeout=>int) Returns a hash with the resulting
tree if mode is set to "block".
See DiscoItemsParse for the format
of the resulting tree.
See MODES above for using the mode
and timeout.
DiscoItemsParse(Net::Jabber::Query) - parses the query and
returns a hash ref
to the resulting tree:
$items{jid}->{node} = name;
$items{"proxy.server"}->{""} = "Bytestream Proxy Server";
$items{"conf.server"}->{"public"} = "Public Chatrooms";
$items{"conf.server"}->{"private"} = "Private Chatrooms";
Feature Negotiation Functions
FeatureNegRequest(jid=>string, - sends a feature negotiation to
features=>hash ref, the jid passed as an argument,
mode=>string, using the features specified.
timeout=>int) Returns a hash with the resulting
tree if mode is set to "block".
See DiscoInfoQuery for the format
of the features hash ref.
See DiscoInfoParse for the format
of the resulting tree.
See MODES above for using the mode
and timeout.
FeatureNegParse(Net::Jabber::Query) - parses the query and
returns a hash ref
to the resulting tree:
$features->{feat1} = ["opt1","opt2",...];
$features->{feat2} = ["optA","optB",...];
....
If this is a result:
$features->{feat1} = "opt2";
$features->{feat2} = "optA";
....
FeatureNeqQuery(hash ref) - takes a hash ref and turns it into a
feature negotiation query that you can
AddQuery into your packaet. The format
of the hash ref is as follows:
$features->{feat1} = ["opt1","opt2",...];
$features->{feat2} = ["optA","optB",...];
....
File Transfer Functions
FileTransferOffer(jid=>string, - sends a file transfer stream
sid=>string, initiation to the jid passed
filename=>string, as an argument. Returns the
mode=>string, method (if the users accepts),
timeout=>int) undef (if the user declines),
if the mode is set to "block".
See MODES above for using
the mode and timeout.
Last Functions
LastQuery(to=>string, - asks the jid specified for its last
mode=>string, activity. If the to is blank, then it
timeout=>int) queries the server. Returns a hash with
LastQuery() the various items set if mode is set to
"block":
$last{seconds} - Seconds since activity
$last{message} - Message for activity
See MODES above for using the mode
and timeout.
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.
Multi-User Chat Functions
MUCJoin(room=>string, - Sends the appropriate MUC protocol to join
server=>string, the specified room with the specified nick.
nick=>string,
password=>string)
Register Functions
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.
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
mode=>string, the above data from RPCParse.
timeout=>int)
See MODES above for using the mode
and timeout.
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" or "int: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.
Search Functions
SearchRequest(to=>string, - send an <iq/> request to the specified
mode=>string, server/transport, if not specified it
timeout=>int) sends to the current active server.
SearchRequest() 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.
See MODES above for using the mode
and timeout.
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.
Time Functions
TimeQuery(to=>string, - asks the jid specified for its localtime.
mode=>string, If the to is blank, then it queries the
timeout=>int) server. Returns a hash with the various
TimeQuery() items set if mode is set to "block":
$time{utc} - Time in UTC
$time{tz} - Timezone
$time{display} - Display string
See MODES above for using the mode
and timeout.
TimeSend(to=>string) - sends the current UTC time to the specified
jid.
Version Functions
VersionQuery(to=>string, - asks the jid specified for its
mode=>string, client version information. If the
timeout=>int) to is blank, then it queries the
VersionQuery() server. Returns ahash with the
various items set if mode is set to
"block":
$version{name} - Name
$version{ver} - Version
$version{os} - Operating System/
Platform
See MODES above for using the mode
and timeout.
VersionSend(to=>string, - sends the specified version information
name=>string, to the jid specified in the to.
ver=>string,
os=>string)
AUTHOR
Ryan EatmonCOPYRIGHT
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.