1Net::XMPP::Presence(3)User Contributed Perl DocumentationNet::XMPP::Presence(3)
2
6 Net::XMPP::Presence - XMPP Presence Module
7
9 Net::XMPP::Presence is a companion to the Net::XMPP module.
10 It provides the user a simple interface to set and retrieve all
11 parts of an XMPP Presence.
12
14 A Net::XMPP::Presence object is passed to the callback function for
15 the message. Also, the first argument to the callback functions is
16 the session ID from XML::Streams. There are some cases where you
17 might want this information, like if you created a Client that
18 connects to two servers at once, or for writing a mini server.
19 use Net::XMPP;
21 sub presence {
23 my ($sid,$Pres) = @_;
24 .
25 .
26 .
27 }
28 You now have access to all of the retrieval functions available.
30 To create a new presence to send to the server:
32 use Net::XMPP;
34 $Pres = new Net::XMPP::Presence();
36 Now you can call the creation functions below to populate the tag
38 before sending it.
39
41 Retrieval functions
42 GetTo() - returns the value in the to='' attribute for the
43 GetTo("jid") <presence/>. If you specify "jid" as an argument
44 then a Net::XMPP::JID object is returned and
45 you can easily parse the parts of the JID.
46 $to = $Pres->GetTo();
48 $toJID = $Pres->GetTo("jid");
49 GetFrom() - returns the value in the from='' attribute for the
51 GetFrom("jid") <presence/>. If you specify "jid" as an argument
52 then a Net::XMPP::JID object is returned and
53 you can easily parse the parts of the JID.
54 $from = $Pres->GetFrom();
56 $fromJID = $Pres->GetFrom("jid");
57 GetType() - returns the type='' attribute of the <presence/>. Each
59 presence is one of seven types:
60 available available to receive messages; default
62 unavailable unavailable to receive anything
63 subscribe ask the recipient to subscribe you
64 subscribed tell the sender they are subscribed
65 unsubscribe ask the recipient to unsubscribe you
66 unsubscribed tell the sender they are unsubscribed
67 probe probe
68 $type = $Pres->GetType();
70 GetStatus() - returns a string with the current status of the resource.
72 $status = $Pres->GetStatus();
74 GetPriority() - returns an integer with the priority of the resource
76 The default is 0 if there is no priority in this
77 presence.
78 $priority = $Pres->GetPriority();
80 GetShow() - returns a string with the state the client should show.
82 $show = $Pres->GetShow();
84 Creation functions
86 SetPresence(to=>string|JID - set multiple fields in the <presence/>
87 from=>string|JID, at one time. This is a cumulative
88 type=>string, and over writing action. If you set
89 status=>string, the "to" attribute twice, the second
90 priority=>integer, setting is what is used. If you set
91 meta=>string, the status, and then set the priority
92 icon=>string, then both will be in the <presence/>
93 show=>string, tag. For valid settings read the
94 loc=>string) specific Set functions below.
95 $Pres->SetPresence(TYPE=>"away",
97 StatuS=>"Out for lunch");
98 SetTo(string) - sets the to attribute. You can either pass a string
100 SetTo(JID) or a JID object. They must be valid JIDs or the
101 server will return an error message.
102 (ie. bob@jabber.org/Silent Bob, etc...)
103 $Pres->SetTo("bob\@jabber.org");
105 SetFrom(string) - sets the from='' attribute. You can either pass
107 SetFrom(JID) a string or a JID object. They must be valid JIDs
108 or the server will return an error message. (ie.
109 jabber:bob@jabber.org/Work) This field is not
110 required if you are writing a Client since the
111 server will put the JID of your connection in there
112 to prevent spamming.
113 $Pres->SetFrom("jojo\@jabber.org");
115 SetType(string) - sets the type attribute. Valid settings are:
117 available available to receive messages; default
119 unavailable unavailable to receive anything
120 subscribe ask the recipient to subscribe you
121 subscribed tell the sender they are subscribed
122 unsubscribe ask the recipient to unsubscribe you
123 unsubscribed tell the sender they are unsubscribed
124 probe probe
125 $Pres->SetType("unavailable");
127 SetStatus(string) - sets the status tag to be whatever string the user
129 wants associated with that resource.
130 $Pres->SetStatus("Taking a nap");
132 SetPriority(integer) - sets the priority of this resource. The highest
134 resource attached to the xmpp account is the
135 one that receives the messages.
136 $Pres->SetPriority(10);
138 SetShow(string) - sets the name of the icon or string to display for
140 this resource.
141 $Pres->SetShow("away");
143 Reply(hash) - creates a new Presence object and populates the to/from
145 fields. If you specify a hash the same as with
146 SetPresence then those values will override the Reply
147 values.
148 $Reply = $Pres->Reply();
150 $Reply = $Pres->Reply(type=>"subscribed");
151 Removal functions
153 RemoveTo() - removes the to attribute from the <presence/>.
154 $Pres->RemoveTo();
156 RemoveFrom() - removes the from attribute from the <presence/>.
158 $Pres->RemoveFrom();
160 RemoveType() - removes the type attribute from the <presence/>.
162 $Pres->RemoveType();
164 RemoveStatus() - removes the <status/> element from the <presence/>.
166 $Pres->RemoveStatus();
168 RemovePriority() - removes the <priority/> element from the
170 <presence/>.
171 $Pres->RemovePriority();
173 RemoveShow() - removes the <show/> element from the <presence/>.
175 $Pres->RemoveShow();
177 Test functions
179 DefinedTo() - returns 1 if the to attribute is defined in the
180 <presence/>, 0 otherwise.
181 $test = $Pres->DefinedTo();
183 DefinedFrom() - returns 1 if the from attribute is defined in the
185 <presence/>, 0 otherwise.
186 $test = $Pres->DefinedFrom();
188 DefinedType() - returns 1 if the type attribute is defined in the
190 <presence/>, 0 otherwise.
191 $test = $Pres->DefinedType();
193 DefinedStatus() - returns 1 if <status/> is defined in the
195 <presence/>, 0 otherwise.
196 $test = $Pres->DefinedStatus();
198 DefinedPriority() - returns 1 if <priority/> is defined in the
200 <presence/>, 0 otherwise.
201 $test = $Pres->DefinedPriority();
203 DefinedShow() - returns 1 if <show/> is defined in the <presence/>,
205 0 otherwise.
206 $test = $Pres->DefinedShow();
208
210 Ryan Eatmon
211
213 This module is free software, you can redistribute it and/or modify it
214 under the LGPL.
215perl v5.12.0 2010-05-04 Net::XMPP::Presence(3)