Net::Jabber::Protocol - Jabber Protocol Library
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.
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.
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); $error = $Con->GetErrorCode(); $Con->SetErrorCode("Timeout limit reached"); $Con->Process(); $Con->Process(5); $Con->Send($object); $Con->Send("<tag>XML</tag>"); $Con->Disconnect();
$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);
$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"]}]);
$Con->MessageSend(to=>"bob@jabber.org", subject=>"Lunch", body=>"Let's go grab some...\n"; thread=>"ABC123", priority=>10);
$Con->PresenceSend();
$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");
$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);
%agents = $Con->AgentsGet(); %agents = $Con->AgentsGet(to=>"transport.jabber.org");
@result = $Con->AuthSend(); @result = $Con->AuthSend(username=>"bob", password=>"bobrulez", resource=>"Bob");
%hash = $Con->BrowseRequest("jabber.org");
$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);
$Con->LastQuery(); $Con->LastQuery(to=>"bob@jabber.org"); %result = $Con->LastQuery(waitforid=>1); %result = $Con->LastQuery(to=>"bob@jabber.org", waitforid=>1); $Con->TimeSend(to=>"bob@jabber.org");
%hash = $Con->RegisterRequest(); %hash = $Con->RegisterRequest(to=>"transport.jabber.org"); @result = $Con->RegisterSend(usersname=>"newuser", resource=>"New User", password=>"imanewbie", email=>"newguy@new.com", key=>"some key");
%roster = $Con->RosterParse($iq); %roster = $Con->RosterGet(); $Con->RosterAdd(jid=>"bob\@jabber.org", name=>"Bob"); $Con->RosterRemove(jid=>"bob@jabber.org");
%fields = $Con->SearchRequest(); %fields = $Con->SearchRequest(to=>"users.jabber.org"); $Con->SearchSend(name=>"", first=>"Bob", last=>"", nick=>"bob", email=>"", key=>"som key");
$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");
$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");
$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 );
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. 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.
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.
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.
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.
PresenceSend() - sends an empty Presence to the server to tell it that you are available
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 unsubscribe
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.
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.
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.
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.
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.
LastQuery(to=>string, - asks the jid specified for its last waitforid=>0|1) activity. If the to is blank, then it LastQuery() queries the server. Returns a hash with the various items set if waitforid is set to 1: $last{seconds} - Seconds since activity $last{message} - Message for activity 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.
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: $hash{fields} - The raw fields from the iq:register. To be used if there is no x:form in the packet. $hash{isntructions} - 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.
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.
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 Net::Jabber::Query jabber:iq:search namespace. And then sends the packet.
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.
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)
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.
By Ryan Eatmon in May of 2001 for http://jabber.org
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Net::Jabber, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Jabber
CPAN shell
perl -MCPAN -e shell install Net::Jabber
For more information on module installation, please visit the detailed CPAN module installation guide.