NAME
Net::Jabber::Protocol - Jabber Protocol Library
SYNOPSIS
Net::Jabber::Protocol is a module that provides a developer easyaccess to the Jabber Instant Messaging protocol. It provides highlevel functions to the Net::Jabber Client, Component, and Serverobjects. These functions are automatically indluded in those modulesthrough AUTOLOAD and delegates.
DESCRIPTION
Protocol.pm seeks to provide enough high level APIs and automation ofthe low level APIs that writing a Jabber Client/Transport in Perl istrivial. For those that wish to work with the low level you can dothat too, but those functions are covered in the documentation foreach module.Net::Jabber::Protocol provides functions to login, send and receivemessages, set personal information, create a new user account, managethe 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 writtenplease 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 howthe function should behave:block - send the packet with an ID, and then block until an answercomes back. You can optionally specify a timeout so thatyou do not block forever.nonblock - send the packet with an ID, but then return that id andcontrol to the master program. Net::Jabber is stilltracking this packet, so you must use the CheckID functionto tell when it comes in. (This might not be veryuseful...)passthru - send the packet with an ID, but do NOT register it withNet::Jabber, then return the ID. This is useful whencombined with the XPath function because you can registera 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::Clientoruse Net::Jabber qw( Component );$Con = new Net::Jabber::Component(); #$status = $Con->Connect(hostname=>"jabber.org", # Fromsecret=>"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::Jabberversion=>string) can auto-reply to some packets for you toreduce the work you have to do.NOTE: This requires that you use theSetIQCallBacks methodology and not theSetCallBacks for <iq/> packets.
IQ Functions
Agents Functions
********************************* ** Deprecated in favor of Disco ** *********************************AgentsGet(to=>string, - takes all of the information andAgentsGet() builds a Net::Jabber::IQ::Agents packet.It then sends that packet either to theserver, or to the specified transport,with an ID and waits for that ID to return.Then it looks in the resulting packet andbuilds a hash that contains the valuesof the agent list. The hash is layed outlike this: (NOTE: the jid is the key todistinguish the various agents)$hash{<JID>}->{order} = 4->{name} = "ICQ Transport"->{transport} = "ICQ #"->{description} = "ICQ..blah.."->{service} = "icq"->{register} = 1->{search} = 1etc...The order field determines the order thatit came from the server in... in case youcare. For more info on the valid fieldssee the Net::Jabber::Query jabber:iq:agentnamespace.
Browse Functions
********************************* ** Deprecated in favor of Disco ** *********************************BrowseRequest(jid=>string, - sends a jabber:iq:browse request tomode=>string, the jid passed as an argument.timeout=>int) Returns a hash with the resultingtree 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 thenamespaces that this jid supports.The children array points to hashsof this form, and represent the factthat they can be browsed to.See MODES above for using the modeand timeout.
Browse DB Functions
BrowseDBDelete(string|Net::Jabber::JID) - delete thes JID browsedata from the DB.BrowseDBQuery(jid=>string | NJ::JID, - returns the browse datatimeout=>integer, for the requested JID. Ifrefresh=>0|1) the DB does not containthe data for the JID, thenit attempts to fetch thedata via BrowseRequest().The timeout is passed tothe BrowseRequest() call,and refresh tells the DBto request the data, evenif it already has some.
Bytestreams Functions
ByteStreamsProxyRequest(jid=>string, - sends a bytestreams requestmode=>string, to the jid passed as antimeout=>int) argument. Returns an arrayref with the resulting treeif mode is set to "block".See ByteStreamsProxyParsefor the format of theresulting tree.See MODES above for usingthe mode and timeout.ByteStreamsProxyParse(Net::Jabber::Query) - parses the query andreturns an array refto 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 activatesid=>string, to the jid passed as anmode=>string, argument. Returns 1 if thetimeout=>int) proxy activated (undef ifit did not) if mode is setto "block".sid is the stream id thatis being used to talk aboutthis stream.See MODES above for usingthe mode and timeout.ByteStreamsOffer(jid=>string, - sends a bytestreams offersid=>string, to the jid passed as anstreamhosts=>arrayref argument. Returns the jidmode=>string, of the streamhost that thetimeout=>int) user selected if mode is setto "block".streamhosts is the sameformat as the array refreturned fromByteStreamsProxyParse.See MODES above for usingthe mode and timeout.
Disco Functions
DiscoInfoRequest(jid=>string, - sends a disco#info request tonode=>string, the jid passed as an argument,mode=>string, and the node if specified.timeout=>int) Returns a hash with the resultingtree if mode is set to "block".See DiscoInfoParse for the formatof the resulting tree.See MODES above for using the modeand timeout.DiscoInfoParse(Net::Jabber::Query) - parses the query andreturns a hash refto 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 tomode=>string, the jid passed as an argument.timeout=>int) Returns a hash with the resultingtree if mode is set to "block".See DiscoItemsParse for the formatof the resulting tree.See MODES above for using the modeand timeout.DiscoItemsParse(Net::Jabber::Query) - parses the query andreturns a hash refto 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 tofeatures=>hash ref, the jid passed as an argument,mode=>string, using the features specified.timeout=>int) Returns a hash with the resultingtree if mode is set to "block".See DiscoInfoQuery for the formatof the features hash ref.See DiscoInfoParse for the formatof the resulting tree.See MODES above for using the modeand timeout.FeatureNegParse(Net::Jabber::Query) - parses the query andreturns a hash refto 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 afeature negotiation query that you canAddQuery into your packaet. The formatof the hash ref is as follows:$features->{feat1} = ["opt1","opt2",...];$features->{feat2} = ["optA","optB",...];....
File Transfer Functions
FileTransferOffer(jid=>string, - sends a file transfer streamsid=>string, initiation to the jid passedfilename=>string, as an argument. Returns themode=>string, method (if the users accepts),timeout=>int) undef (if the user declines),if the mode is set to "block".See MODES above for usingthe mode and timeout.
Last Functions
LastQuery(to=>string, - asks the jid specified for its lastmode=>string, activity. If the to is blank, then ittimeout=>int) queries the server. Returns a hash withLastQuery() the various items set if mode is set to"block":$last{seconds} - Seconds since activity$last{message} - Message for activitySee MODES above for using the modeand timeout.LastSend(to=>string, - sends the specified last to the specified jid.hash) the hash is the seconds and message as shownin the Net::Jabber::Query man page.LastActivity() - returns the number of seconds since the last activityby the user.
Multi-User Chat Functions
MUCJoin(room=>string, - Sends the appropriate MUC protocol to joinserver=>string, the specified room with the specified nick.nick=>string,password=>string)
Register Functions
RegisterSendData(string|JID, - takes the contents of the hash andhash) builds a jabebr:x:data return packetwhich it sends in a Net::Jabber::Queryjabber:iq:register namespace packet.The first argument is the JID to sendthe packet to. This function returnsan array that looks like this:[ type , message ]If type is "ok" then registration wassuccessful, otherwise message containsa little more detail about the error.
RPC Functions
RPCParse(IQ object) - returns an array. The first argument tellsthe status "ok" or "fault". The secondargument 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 itparams=>array, to the specified address. Returnsmode=>string, the above data from RPCParse.timeout=>int)See MODES above for using the modeand timeout.RPCResponse(to=>jid|string, - generates a response back toparams=>array, the caller. If any part offaultCode=>int, fault is specified, then itfaultString=>string) wins.Note: To ensure that you get the correct type for a param sentback, you can specify the type by prepending the type tothe value:"i4:5" or "int:5""boolean:0""string:56""double:5.0""datetime:20020415T11:11:11""base64:...."RPCSetCallBacks(method=>function, - sets the callback functionsmethod=>function, for the specified methods.etc...) The method comes from the<methodName/> and is casesensitive. The singlearguemnt is a ref to anarray that contains the<params/>. The function youwrite should return one of twothings:["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 fromthe list.
Search Functions
SearchRequest(to=>string, - send an <iq/> request to the specifiedmode=>string, server/transport, if not specified ittimeout=>int) sends to the current active server.SearchRequest() The function returns a hash thatcontains the required fields. Hereis an example of the hash:$hash{fields} - The raw fields fromthe iq:register. Tobe used if there isno x:data in thepacket.$hash{instructions} - How to fill outthe form.$hash{form} - The new dynamic forms.In $hash{form}, the fields that arepresent are the required fields theserver needs.See MODES above for using the modeand timeout.SearchSend(to=>string|JID, - takes the contents of the hash andhash) passes it to the SetSearch functionin the Net::Jabber::Queryjabber:iq:search namespace. And thensends the packet.SearchSendData(string|JID, - takes the contents of the hash andhash) builds a jabebr:x:data return packetwhich it sends in a Net::Jabber::Queryjabber:iq:search namespace packet.The first argument is the JID to sendthe packet to.
Time Functions
TimeQuery(to=>string, - asks the jid specified for its localtime.mode=>string, If the to is blank, then it queries thetimeout=>int) server. Returns a hash with the variousTimeQuery() items set if mode is set to "block":$time{utc} - Time in UTC$time{tz} - Timezone$time{display} - Display stringSee MODES above for using the modeand timeout.TimeSend(to=>string) - sends the current UTC time to the specifiedjid.
Version Functions
VersionQuery(to=>string, - asks the jid specified for itsmode=>string, client version information. If thetimeout=>int) to is blank, then it queries theVersionQuery() server. Returns ahash with thevarious items set if mode is set to"block":$version{name} - Name$version{ver} - Version$version{os} - Operating System/PlatformSee MODES above for using the modeand timeout.VersionSend(to=>string, - sends the specified version informationname=>string, to the jid specified in the to.ver=>string,os=>string)
AUTHOR
Ryan Eatmon
COPYRIGHT
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.