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 both Net::Jabber::Client and Net::Jabber::Transport. 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; $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(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("<tag>XML</tag>"); $yesno = $Con->ReceivedID($id); $receiveObj = $Con->GetID($id); $receiveObj = $Con->WaitForID($id);
$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->SetQueryDelegates("com:bar:foo"=>"Foo::Bar");
%agents = $Con->AgentsGet(); %agents = $Con->AgentsGet(to=>"transport.jabber.org");
@result = $Con->AuthSend(); @result = $Con->AuthSend(username=>"bob", password=>"bobrulez", resource=>"Bob");
n/a
%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");
%roster = $Con->RosterParse($iq); %roster = $Con->RosterGet(); $Con->RosterAdd(jid=>"bob\@jabber.org", name=>"Bob"); $Con->RosterRemove(jid=>"bob@jabber.org");
%result = $Con->TimeQuery(); %result = $Con->TimeQuery(to=>"bob@jabber.org"); $Con->TimeSend(to=>"bob@jabber.org");
%result = $Con->VersionQuery(); %result = $Con->VersionQuery(to=>"bob@jabber.org"); $Con->VersionSend(to=>"bob@jabber.org", name=>"Net::Jabber", ver=>"1.0a", os=>"Perl");
$Con->SetXDelegates("com:bar:foo"=>"Foo::Bar");
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 <message/>, <presence/>, and <iq/>. If a packet is received with an ID 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.
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.
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
SetQueryDelegates(hash) - the hash gets sent to the Net::Jabber::Query::SetDelegates function. For more information about this function, read the manpage for Net::Jabber::Query.
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.
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 AuthSend() 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. If no hash is passed then it tries to open an anonymous session. 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.
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.
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.
TimeQuery(to=>string) - asks the jid specified for its local time. TimeQuery() If the to is blank, then it queries the server. Returns a hash with the various items set: $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 client VersionQuery() version information. If the to is blank, then it queries the server. Returns a hash with the various items set: $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)
SetXDelegates(hash) - the hash gets sent to the Net::Jabber::X::SetDelegates function. For more information about this function, read the manpage for Net::Jabber::X.
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/
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.